1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-12-27 07:50:57 +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:
vrana 2012-06-01 13:04:01 -07:00
parent 8d37576bd8
commit fd10bcea48
2 changed files with 27 additions and 42 deletions

View file

@ -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 =

View file

@ -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 =