Differential D25007 Diff 23 src/docs/contributor/phorge_code_layout.diviner

Changeset View

Standalone View

src/docs/contributor/phorge_code_layout.diviner

This file was moved from src/docs/contributor/phabricator_code_layout.diviner.

	@title Phabricator Code Layout			@title Phorge Code Layout
	@group developer			@group developer

	Guide to Phabricator code layout, including how URI mapping works through			Guide to Phorge 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 =

	When a user visits a Phabricator URI, the Phabricator infrastructure parses			When a user visits a Phorge URI, the Phorge infrastructure parses that URI with
	that URI with a regular expression to determine what controller class to load.			a regular expression to determine what controller class to load.

	The Phabricator infrastructure knows where a given controller class lives on			The Phorge 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/phorge/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/			phorge/src/applications/derp/

	If `Derp` were as simple as possible, it would have one subdirectory:			If `Derp` were as simple as possible, it would have one subdirectory:

	phabricator/src/applications/derp/controller/			phorge/src/applications/derp/controller/

	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}.

	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:			the following directory layout:

	phabricator/src/applications/derp/conduit/			phorge/src/applications/derp/conduit/
	phabricator/src/applications/derp/constants/			phorge/src/applications/derp/constants/
	phabricator/src/applications/derp/controller/			phorge/src/applications/derp/controller/
	phabricator/src/applications/derp/editor/			phorge/src/applications/derp/editor/
	phabricator/src/applications/derp/exception/			phorge/src/applications/derp/exception/
	phabricator/src/applications/derp/query/			phorge/src/applications/derp/query/
	phabricator/src/applications/derp/replyhandler/			phorge/src/applications/derp/replyhandler/
	phabricator/src/applications/derp/storage/			phorge/src/applications/derp/storage/
	phabricator/src/applications/derp/view/			phorge/src/applications/derp/view/

	(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/rsrc/js/application/derp/			phorge/webroot/rsrc/js/application/derp/
	phabricator/webroot/rsrc/css/application/derp/			phorge/webroot/rsrc/css/application/derp/

	These directories under `phabricator/src/applications/derp/` represent			These directories under `phorge/src/applications/derp/` represent
	the basic set of class types from which most Phabricator applications are			the basic set of class types from which most Phorge applications are
	assembled. Each would contain a class file. For `Derp`, these classes could be			assembled. Each would contain a class file. 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
	▲ Show 20 Lines • Show All 45 Lines • Show Last 20 Lines