recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Phorge Code Layout
2@group developer
3
4Guide to Phorge code layout, including how URI mapping works through
5application class and subdirectory organization best practices.
6
7= URI Mapping =
8
9When a user visits a Phorge URI, the Phorge infrastructure parses that URI with
10 a regular expression to determine what controller class to load.
11
12The Phorge infrastructure knows where a given controller class lives on
13disk from a cache file the Arcanist phutil mapper generates. This mapping
14should be updated whenever new classes or files are added:
15
16 arc liberate /path/to/phorge/src
17
18Finally, a given controller class will map to an application which will have
19most of its code in standardized subdirectories and classes.
20
21= Best Practice Class and Subdirectory Organization =
22
23Suppose you were working on the application `Derp`.
24
25 phorge/src/applications/derp/
26
27If `Derp` were as simple as possible, it would have one subdirectory:
28
29 phorge/src/applications/derp/controller/
30
31containing the file `DerpController.php` with the class
32
33 - `DerpController`: minimally implements a `processRequest()` method
34 which returns some @{class:AphrontResponse} object. The class would probably
35 extend @{class:PhabricatorController}.
36
37If `Derp` were (relatively) complex, one could reasonably expect to see
38the following directory layout:
39
40 phorge/src/applications/derp/conduit/
41 phorge/src/applications/derp/constants/
42 phorge/src/applications/derp/controller/
43 phorge/src/applications/derp/editor/
44 phorge/src/applications/derp/exception/
45 phorge/src/applications/derp/query/
46 phorge/src/applications/derp/replyhandler/
47 phorge/src/applications/derp/storage/
48 phorge/src/applications/derp/view/
49
50(The following two folders are also likely to be included for JavaScript and
51CSS respectively. However, static resources are largely outside the scope of
52this document. See @{article:Adding New CSS and JS}.)
53
54 phorge/webroot/rsrc/js/application/derp/
55 phorge/webroot/rsrc/css/application/derp/
56
57These directories under `phorge/src/applications/derp/` represent
58the basic set of class types from which most Phorge applications are
59assembled. Each would contain a class file. For `Derp`, these classes could be
60something like:
61
62 - **DerpConstants**: constants used in the `Derp` application.
63 - **DerpController**: business logic providing functionality for a given
64 URI. Typically, controllers load data via Storage or Query classes, then
65 present the data to the user via one or more View classes.
66 - **DerpEditor**: business logic for workflows that change one or more
67 Storage objects. Editor classes are only necessary for particularly
68 complicated edits and should be used pragmatically versus Storage objects.
69 - **DerpException**: exceptions used in the `Derp` application.
70 - **DerpQuery**: query one or more storage objects for pertinent `Derp`
71 application data. @{class:PhabricatorOffsetPagedQuery} is particularly
72 handy for pagination and works well with @{class:AphrontPagerView}.
73 - **DerpReplyHandler**: business logic from any configured email interactions
74 users can have with the `Derp` application.
75 - **DerpStorage**: storage objects for the `Derp` application. Typically
76 there is a base class which extends @{class:PhabricatorLiskDAO} to configure
77 application-wide storage settings like the application (thus database) name.
78 Reading more about the @{class:LiskDAO} is highly recommended.
79 - **DerpView**: view objects for the `Derp` application. Typically these
80 extend @{class:AphrontView}.
81 - **DerpConduitAPIMethod**: provides any and all `Derp` application
82 functionality that is accessible over Conduit.
83
84However, it is likely that `Derp` is even more complex, and rather than
85containing one class, each directory has several classes. A typical example
86happens around the CRUD of an object:
87
88 - **DerpBaseController**: typically extends @{class:PhabricatorController}
89 and contains any controller-specific functionality used throughout the
90 `Derp` application.
91 - **DerpDeleteController**: typically extends `DerpBaseController` and
92 presents a confirmation dialogue to the user about deleting a `Derp`.
93 - **DerpEditController**: typically extends `DerpBaseController` and
94 presents a form to create and edit `Derps`. Most likely uses
95 @{class:AphrontFormView} and various `AphrontFormXControl` classes such as
96 @{class:AphrontFormTextControl} to create the form.
97 - **DerpListController**: typically extends `DerpBaseController` and displays
98 a set of one or more `Derps`. Might use @{class:AphrontTableView} to create
99 a table of `Derps`.
100 - **DerpViewController**: typically extends `DerpBaseController` and displays
101 a single `Derp`.
102
103Some especially awesome directories might have a `__tests__` subdirectory
104containing all pertinent unit test code for the class.
105
106= Next Steps =
107
108 - Learn about @{article:Adding New CSS and JS}; or
109 - learn about the @{class:LiskDAO}; or
110 - learn about @{article:Writing Unit Tests}; or
111 - learn how to contribute (see @{article:Contributor Introduction}).