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
|
@group developer
|
||||||
|
|
||||||
Guide to Phabricator code layout, including how URI mapping works through
|
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 =
|
= 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.
|
method. Use the existing entries as examples for adding your own entries.
|
||||||
|
|
||||||
The Phabricator infrastructure knows where a given controller class lives on
|
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:
|
should be updated whenever new classes or files are added:
|
||||||
|
|
||||||
arc liberate /path/to/phabricator/src
|
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.
|
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/
|
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
|
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
|
which returns some @{class:AphrontResponse} object. The class would probably
|
||||||
extend @{class:PhabricatorController}.
|
extend @{class:PhabricatorController}.
|
||||||
|
|
||||||
plus an auto-generated ##__init__.php## file.
|
If ##Derp## were (relatively) complex, one could reasonably expect to see
|
||||||
|
|
||||||
NOTE: ##__init.php__## files are generated and maintained via `arc lint`.
|
|
||||||
|
|
||||||
If ##Derp## were (relatively) complex, one could reasonably expect to see
|
|
||||||
the following directory layout:
|
the following directory layout:
|
||||||
|
|
||||||
phabricator/src/applications/derp/constants/
|
phabricator/src/applications/derp/constants/
|
||||||
|
@ -54,24 +50,24 @@ the following directory layout:
|
||||||
phabricator/src/applications/derp/view/
|
phabricator/src/applications/derp/view/
|
||||||
phabricator/src/applications/conduit/method/derp/
|
phabricator/src/applications/conduit/method/derp/
|
||||||
|
|
||||||
(The following two folders are also likely to be included for javascript and
|
(The following two folders are also likely to be included for JavaScript and
|
||||||
css respectively. However, static resources are largely outside the scope of
|
CSS respectively. However, static resources are largely outside the scope of
|
||||||
this document. See @{article:Adding New CSS and JS}.)
|
this document. See @{article:Adding New CSS and JS}.)
|
||||||
|
|
||||||
phabricator/webroot/rsc/js/application/derp/
|
phabricator/webroot/rsrc/js/application/derp/
|
||||||
phabricator/webroot/rsc/css/application/derp/
|
phabricator/webroot/rsrc/css/application/derp/
|
||||||
|
|
||||||
These directories under ##phabricator/src/applications/derp/## represent
|
These directories under ##phabricator/src/applications/derp/## represent
|
||||||
the basic set of class types from which most Phabrictor applications are
|
the basic set of class types from which most Phabrictor applications are
|
||||||
assembled. Each would contain a class file and an ##__init__.php## file.
|
assembled. Each would contain a class file. For ##Derp##, these classes could be
|
||||||
For ##Derp##, these classes could be something like:
|
something like:
|
||||||
|
|
||||||
- **DerpConstants**: constants used in the ##Derp## application.
|
- **DerpConstants**: constants used in the ##Derp## application.
|
||||||
- **DerpController**: business logic providing functionality for a given
|
- **DerpController**: business logic providing functionality for a given
|
||||||
URI. Typically, controllers load data via Storage or Query classes, then
|
URI. Typically, controllers load data via Storage or Query classes, then
|
||||||
present the data to the user via one or more View classes.
|
present the data to the user via one or more View classes.
|
||||||
- **DerpEditor**: business logic for workflows that change one or more
|
- **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.
|
complicated edits and should be used pragmatically versus Storage objects.
|
||||||
- **DerpException**: exceptions used in the ##Derp## application.
|
- **DerpException**: exceptions used in the ##Derp## application.
|
||||||
- **DerpQuery**: query one or more storage objects for pertinent ##Derp##
|
- **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}.
|
handy for pagination and works well with @{class:AphrontPagerView}.
|
||||||
- **DerpReplyHandler**: business logic from any configured email interactions
|
- **DerpReplyHandler**: business logic from any configured email interactions
|
||||||
users can have with the ##Derp## application.
|
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
|
there is a base class which extends @{class:PhabricatorLiskDAO} to configure
|
||||||
application-wide storage settings like the application (thus database) name.
|
application-wide storage settings like the application (thus database) name.
|
||||||
Reading more about the @{class:LiskDAO} is highly recommended.
|
Reading more about the @{class:LiskDAO} is highly recommended.
|
||||||
- **DerpView**: view objects for the ##Derp## application. Typically these
|
- **DerpView**: view objects for the ##Derp## application. Typically these
|
||||||
extend @{class:AphrontView}.
|
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.
|
functionality that is accessible over Conduit.
|
||||||
|
|
||||||
However, it is likely that ##Derp## is even more complex, and rather than
|
However, it is likely that ##Derp## is even more complex, and rather than
|
||||||
containing a class and an ##__init__.php## file, each directory has
|
containing one class, each directory has several classes. A typical example
|
||||||
subdirectories of its own. A typical example happens around the CRUD of an
|
happens around the CRUD of an object:
|
||||||
object:
|
|
||||||
|
|
||||||
phbaricator/src/application/derp/controller/base/
|
- **DerpBaseController**: typically extends @{class:PhabricatorController},
|
||||||
phabricator/src/application/derp/controller/delete/
|
implements ##buildStandardPageResponse## with the ##Derp## application name
|
||||||
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
|
|
||||||
and other ##Derp##-specific meta-data, and contains any controller-specific
|
and other ##Derp##-specific meta-data, and contains any controller-specific
|
||||||
functionality used throughout the ##Derp## application.
|
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##.
|
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
|
presents a form to create and edit ##Derps##. Most likely uses
|
||||||
@{class:AphrontFormView} and various ##AphrontFormXControl## classes such as
|
@{class:AphrontFormView} and various ##AphrontFormXControl## classes such as
|
||||||
@{class:AphrontFormTextControl} to create the form.
|
@{class:AphrontFormTextControl} to create the form.
|
||||||
|
@ -118,7 +104,7 @@ corresponding classes
|
||||||
- **DerpViewController**: typically extends ##DerpBaseController## and displays
|
- **DerpViewController**: typically extends ##DerpBaseController## and displays
|
||||||
a single ##Derp##.
|
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.
|
containing all pertinent unit test code for the class.
|
||||||
|
|
||||||
= Next Steps =
|
= Next Steps =
|
||||||
|
|
|
@ -120,8 +120,7 @@ Now, run ##arc liberate## to regenerate the static resource map:
|
||||||
|
|
||||||
libcustom/ $ arc liberate src/
|
libcustom/ $ arc liberate src/
|
||||||
|
|
||||||
This will automatically create and update ##__init__.php## files, and regenerate
|
This will automatically regenerate the static map of the library.
|
||||||
the static map of the library.
|
|
||||||
|
|
||||||
= What You Can Extend And Invoke =
|
= What You Can Extend And Invoke =
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue