diff --git a/src/docs/developer/phabricator_code_layout.diviner b/src/docs/developer/phabricator_code_layout.diviner index 09d944e529..356228cdd7 100644 --- a/src/docs/developer/phabricator_code_layout.diviner +++ b/src/docs/developer/phabricator_code_layout.diviner @@ -2,7 +2,7 @@ @group developer Guide to Phabricator code layout, including how URI mapping works through -application class and subdirectory organization best practices. +application class and subdirectory organization best practices. = URI Mapping = @@ -13,17 +13,17 @@ For now, that regular expression is hard-coded inside the method. Use the existing entries as examples for adding your own entries. The Phabricator infrastructure knows where a given controller class lives on -disk from a cache file the Arcanist phutil mapper generates. This mapping +disk from a cache file the Arcanist phutil mapper generates. This mapping should be updated whenever new classes or files are added: arc liberate /path/to/phabricator/src -Finally, a given controller class will map to an application which will have +Finally, a given controller class will map to an application which will have most of its code in standardized subdirectories and classes. -= Best Practice Class and Subdirectory Organization = += Best Practice Class and Subdirectory Organization = -Suppose you were working on the application ##Derp##. +Suppose you were working on the application ##Derp##. phabricator/src/applications/derp/ @@ -33,15 +33,11 @@ If ##Derp## were as simple as possible, it would have one subdirectory: containing the file ##DerpController.php## with the class - - ##DerpController##: minimally implements a ##processRequest()## method + - ##DerpController##: minimally implements a ##processRequest()## method which returns some @{class:AphrontResponse} object. The class would probably extend @{class:PhabricatorController}. -plus an auto-generated ##__init__.php## file. - -NOTE: ##__init.php__## files are generated and maintained via `arc lint`. - -If ##Derp## were (relatively) complex, one could reasonably expect to see +If ##Derp## were (relatively) complex, one could reasonably expect to see the following directory layout: phabricator/src/applications/derp/constants/ @@ -54,24 +50,24 @@ the following directory layout: phabricator/src/applications/derp/view/ phabricator/src/applications/conduit/method/derp/ -(The following two folders are also likely to be included for javascript and -css respectively. However, static resources are largely outside the scope of +(The following two folders are also likely to be included for JavaScript and +CSS respectively. However, static resources are largely outside the scope of this document. See @{article:Adding New CSS and JS}.) - phabricator/webroot/rsc/js/application/derp/ - phabricator/webroot/rsc/css/application/derp/ + phabricator/webroot/rsrc/js/application/derp/ + phabricator/webroot/rsrc/css/application/derp/ -These directories under ##phabricator/src/applications/derp/## represent -the basic set of class types from which most Phabrictor applications are -assembled. Each would contain a class file and an ##__init__.php## file. -For ##Derp##, these classes could be something like: +These directories under ##phabricator/src/applications/derp/## represent +the basic set of class types from which most Phabrictor applications are +assembled. Each would contain a class file. For ##Derp##, these classes could be +something like: - **DerpConstants**: constants used in the ##Derp## application. - **DerpController**: business logic providing functionality for a given URI. Typically, controllers load data via Storage or Query classes, then present the data to the user via one or more View classes. - **DerpEditor**: business logic for workflows that change one or more - Storage objects. Editor classes are only necessary for particularly + Storage objects. Editor classes are only necessary for particularly complicated edits and should be used pragmatically versus Storage objects. - **DerpException**: exceptions used in the ##Derp## application. - **DerpQuery**: query one or more storage objects for pertinent ##Derp## @@ -79,36 +75,26 @@ For ##Derp##, these classes could be something like: handy for pagination and works well with @{class:AphrontPagerView}. - **DerpReplyHandler**: business logic from any configured email interactions users can have with the ##Derp## application. - - **DerpStorage**: storage objects for the ##Derp## application. Typically + - **DerpStorage**: storage objects for the ##Derp## application. Typically there is a base class which extends @{class:PhabricatorLiskDAO} to configure application-wide storage settings like the application (thus database) name. Reading more about the @{class:LiskDAO} is highly recommended. - **DerpView**: view objects for the ##Derp## application. Typically these extend @{class:AphrontView}. - - **ConduitAPI_derp_Method**: provides any and all ##Derp## application + - **ConduitAPI_derp_Method**: provides any and all ##Derp## application functionality that is accessible over Conduit. -However, it is likely that ##Derp## is even more complex, and rather than -containing a class and an ##__init__.php## file, each directory has -subdirectories of its own. A typical example happens around the CRUD of an -object: +However, it is likely that ##Derp## is even more complex, and rather than +containing one class, each directory has several classes. A typical example +happens around the CRUD of an object: - phbaricator/src/application/derp/controller/base/ - phabricator/src/application/derp/controller/delete/ - phabricator/src/application/derp/controller/edit/ - phabricator/src/application/derp/controller/list/ - phabricator/src/application/derp/controller/view/ - -Which would then each contain a class and an ##__init__.php## file mapping to -corresponding classes - - - **DerpBaseController**: typically extends @{class:PhabricatorController}, - implements ##buildStandardPageResponse## with the ##Derp## application name + - **DerpBaseController**: typically extends @{class:PhabricatorController}, + implements ##buildStandardPageResponse## with the ##Derp## application name and other ##Derp##-specific meta-data, and contains any controller-specific functionality used throughout the ##Derp## application. - - **DerpDeleteController**: typically extends ##DerpBaseController## and + - **DerpDeleteController**: typically extends ##DerpBaseController## and presents a confirmation dialogue to the user about deleting a ##Derp##. - - **DerpEditController**: typically extends ##DerpBaseController## and + - **DerpEditController**: typically extends ##DerpBaseController## and presents a form to create and edit ##Derps##. Most likely uses @{class:AphrontFormView} and various ##AphrontFormXControl## classes such as @{class:AphrontFormTextControl} to create the form. @@ -118,7 +104,7 @@ corresponding classes - **DerpViewController**: typically extends ##DerpBaseController## and displays a single ##Derp##. -Some especially awesome directories might have a ##__tests__## subdirectory +Some especially awesome directories might have a ##__tests__## subdirectory containing all pertinent unit test code for the class. = Next Steps = diff --git a/src/docs/userguide/libraries.diviner b/src/docs/userguide/libraries.diviner index 2d950d3f45..834b26fe1c 100644 --- a/src/docs/userguide/libraries.diviner +++ b/src/docs/userguide/libraries.diviner @@ -120,8 +120,7 @@ Now, run ##arc liberate## to regenerate the static resource map: libcustom/ $ arc liberate src/ -This will automatically create and update ##__init__.php## files, and regenerate -the static map of the library. +This will automatically regenerate the static map of the library. = What You Can Extend And Invoke =