mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-26 08:42:41 +01:00
Remove references to __init__.php from docs
Test Plan: Regenerate docs. Reviewers: btrahan, epriestley Reviewed By: epriestley CC: aran, Koolvin Maniphest Tasks: T1103 Differential Revision: https://secure.phabricator.com/D2640
This commit is contained in:
parent
8d37576bd8
commit
fd10bcea48
2 changed files with 27 additions and 42 deletions
|
@ -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 =
|
||||
|
|
|
@ -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 =
|
||||
|
||||
|
|
Loading…
Reference in a new issue