[Summary view] [Print] [Text view]

   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 Phabrictor 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     implements ##buildStandardPageResponse## with the ##Derp## application name
  90     and other ##Derp##-specific meta-data, and contains any controller-specific
  91     functionality used throughout the ##Derp## application.
  92   - **DerpDeleteController**: typically extends ##DerpBaseController## and
  93     presents a confirmation dialogue to the user about deleting a ##Derp##.
  94   - **DerpEditController**: typically extends ##DerpBaseController## and
  95     presents a form to create and edit ##Derps##. Most likely uses
  96     @{class:AphrontFormView} and various ##AphrontFormXControl## classes such as
  97     @{class:AphrontFormTextControl} to create the form.
  98   - **DerpListController**: typically extends ##DerpBaseController## and displays
  99     a set of one or more ##Derps##. Might use @{class:AphrontTableView} to create
 100     a table of ##Derps##.
 101   - **DerpViewController**: typically extends ##DerpBaseController## and displays
 102     a single ##Derp##.
 103  
 104  Some especially awesome directories might have a ##__tests__## subdirectory
 105  containing all pertinent unit test code for the class.
 106  
 107  = Next Steps =
 108  
 109   - Learn about @{article:Adding New CSS and JS}; or
 110   - learn about the @{class:LiskDAO}; or
 111   - learn about @{article:Writing Unit Tests}; or
 112   - learn how to contribute (see @{article:Contributor Introduction}).