1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
@title Phabricator Code Layout
@group developer
Guide to Phabricator code layout, including how URI mapping works through
application class and subdirectory organization best practices.
= URI Mapping =
When a user visits a Phabricator URI, the Phabricator infrastructure parses
that URI with a regular expression to determine what controller class to load.
The Phabricator infrastructure knows where a given controller class lives on
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
most of its code in standardized subdirectories and classes.
= Best Practice Class and Subdirectory Organization =
Suppose you were working on the application `Derp`.
phabricator/src/applications/derp/
If `Derp` were as simple as possible, it would have one subdirectory:
phabricator/src/applications/derp/controller/
containing the file `DerpController.php` with the class
- `DerpController`: minimally implements a `processRequest()` method
which returns some @{class:AphrontResponse} object. The class would probably
extend @{class:PhabricatorController}.
If `Derp` were (relatively) complex, one could reasonably expect to see
the following directory layout:
phabricator/src/applications/derp/conduit/
phabricator/src/applications/derp/constants/
phabricator/src/applications/derp/controller/
phabricator/src/applications/derp/editor/
phabricator/src/applications/derp/exception/
phabricator/src/applications/derp/query/
phabricator/src/applications/derp/replyhandler/
phabricator/src/applications/derp/storage/
phabricator/src/applications/derp/view/
(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/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. 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
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`
application data. @{class:PhabricatorOffsetPagedQuery} is particularly
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
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}.
- **DerpConduitAPIMethod**: 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 one class, each directory has several classes. A typical example
happens around the CRUD of an object:
- **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
presents a confirmation dialogue to the user about deleting a `Derp`.
- **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.
- **DerpListController**: typically extends `DerpBaseController` and displays
a set of one or more `Derps`. Might use @{class:AphrontTableView} to create
a table of `Derps`.
- **DerpViewController**: typically extends `DerpBaseController` and displays
a single `Derp`.
Some especially awesome directories might have a `__tests__` subdirectory
containing all pertinent unit test code for the class.
= Next Steps =
- Learn about @{article:Adding New CSS and JS}; or
- learn about the @{class:LiskDAO}; or
- learn about @{article:Writing Unit Tests}; or
- learn how to contribute (see @{article:Contributor Introduction}).
|