src/docs/contributor/phabricator_code_layout.diviner

   1 @title Phabricator Code Layout
   2 @group developer
   3
   4 Guide to Phabricator code layout, including how URI mapping works through
   5 application class and subdirectory organization best practices.
   6
   7 = URI Mapping =
   8
   9 When a user visits a Phabricator URI, the Phabricator infrastructure parses
  10 that URI with a regular expression to determine what controller class to load.
  11
  12 The Phabricator infrastructure knows where a given controller class lives on
  13 disk from a cache file the Arcanist phutil mapper generates. This mapping
  14 should be updated whenever new classes or files are added:
  15
  16   arc liberate /path/to/phabricator/src
  17
  18 Finally, a given controller class will map to an application which will have
  19 most of its code in standardized subdirectories and classes.
  20
  21 = Best Practice Class and Subdirectory Organization =
  22
  23 Suppose you were working on the application `Derp`.
  24
  25   phabricator/src/applications/derp/
  26
  27 If `Derp` were as simple as possible, it would have one subdirectory:
  28
  29   phabricator/src/applications/derp/controller/
  30
  31 containing the file `DerpController.php` with the class
  32
  33  - `DerpController`: minimally implements a `processRequest()` method
  34    which returns some @{class:AphrontResponse} object. The class would probably
  35    extend @{class:PhabricatorController}.
  36
  37 If `Derp` were (relatively) complex, one could reasonably expect to see
  38 the following directory layout:
  39
  40   phabricator/src/applications/derp/conduit/
  41   phabricator/src/applications/derp/constants/
  42   phabricator/src/applications/derp/controller/
  43   phabricator/src/applications/derp/editor/
  44   phabricator/src/applications/derp/exception/
  45   phabricator/src/applications/derp/query/
  46   phabricator/src/applications/derp/replyhandler/
  47   phabricator/src/applications/derp/storage/
  48   phabricator/src/applications/derp/view/
  49
  50 (The following two folders are also likely to be included for JavaScript and
  51 CSS respectively. However, static resources are largely outside the scope of
  52 this document. See @{article:Adding New CSS and JS}.)
  53
  54   phabricator/webroot/rsrc/js/application/derp/
  55   phabricator/webroot/rsrc/css/application/derp/
  56
  57 These directories under `phabricator/src/applications/derp/` represent
  58 the basic set of class types from which most Phabricator applications are
  59 assembled. Each would contain a class file. For `Derp`, these classes could be
  60 something like:
  61
  62  - **DerpConstants**: constants used in the `Derp` application.
  63  - **DerpController**: business logic providing functionality for a given
  64    URI. Typically, controllers load data via Storage or Query classes, then
  65    present the data to the user via one or more View classes.
  66  - **DerpEditor**:  business logic for workflows that change one or more
  67    Storage objects. Editor classes are only necessary for particularly
  68    complicated edits and should be used pragmatically versus Storage objects.
  69  - **DerpException**: exceptions used in the `Derp` application.
  70  - **DerpQuery**: query one or more storage objects for pertinent `Derp`
  71    application data. @{class:PhabricatorOffsetPagedQuery} is particularly
  72    handy for pagination and works well with @{class:AphrontPagerView}.
  73  - **DerpReplyHandler**: business logic from any configured email interactions
  74    users can have with the `Derp` application.
  75  - **DerpStorage**: storage objects for the `Derp` application. Typically
  76    there is a base class which extends @{class:PhabricatorLiskDAO} to configure
  77    application-wide storage settings like the application (thus database) name.
  78    Reading more about the @{class:LiskDAO} is highly recommended.
  79  - **DerpView**: view objects for the `Derp` application. Typically these
  80    extend @{class:AphrontView}.
  81  - **DerpConduitAPIMethod**: provides any and all `Derp` application
  82    functionality that is accessible over Conduit.
  83
  84 However, it is likely that `Derp` is even more complex, and rather than
  85 containing one class, each directory has several classes. A typical example
  86 happens around the CRUD of an object:
  87
  88  - **DerpBaseController**: typically extends @{class:PhabricatorController}
  89    and contains any controller-specific functionality used throughout the
  90    `Derp` application.
  91  - **DerpDeleteController**: typically extends `DerpBaseController` and
  92    presents a confirmation dialogue to the user about deleting a `Derp`.
  93  - **DerpEditController**: typically extends `DerpBaseController` and
  94    presents a form to create and edit `Derps`. Most likely uses
  95    @{class:AphrontFormView} and various `AphrontFormXControl` classes such as
  96    @{class:AphrontFormTextControl} to create the form.
  97  - **DerpListController**: typically extends `DerpBaseController` and displays
  98    a set of one or more `Derps`. Might use @{class:AphrontTableView} to create
  99    a table of `Derps`.
 100  - **DerpViewController**: typically extends `DerpBaseController` and displays
 101    a single `Derp`.
 102
 103 Some especially awesome directories might have a `__tests__` subdirectory
 104 containing all pertinent unit test code for the class.
 105
 106 = Next Steps =
 107
 108  - Learn about @{article:Adding New CSS and JS}; or
 109  - learn about the @{class:LiskDAO}; or
 110  - learn about @{article:Writing Unit Tests}; or
 111  - learn how to contribute (see @{article:Contributor Introduction}).