No OneTemporary
Actions

Size

23 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/applications/base/controller/PhabricatorController.php b/src/applications/base/controller/PhabricatorController.php
	index b0771af094..58641d3cf1 100644
	--- a/src/applications/base/controller/PhabricatorController.php
	+++ b/src/applications/base/controller/PhabricatorController.php
	@@ -1,238 +1,251 @@
	<?php

	/*
	* Copyright 2012 Facebook, Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	abstract class PhabricatorController extends AphrontController {

	private $handles;

	public function shouldRequireLogin() {
	return true;
	}

	public function shouldRequireAdmin() {
	return false;
	}

	public function shouldRequireEnabledUser() {
	return true;
	}

	public function shouldRequireEmailVerification() {
	$need_verify = PhabricatorUserEmail::isEmailVerificationRequired();
	$need_login = $this->shouldRequireLogin();

	return ($need_login && $need_verify);
	}

	final public function willBeginExecution() {

	$request = $this->getRequest();

	$user = new PhabricatorUser();

	$phusr = $request->getCookie('phusr');
	$phsid = $request->getCookie('phsid');

	if (strlen($phusr) && $phsid) {
	$info = queryfx_one(
	$user->establishConnection('r'),
	'SELECT u.* FROM %T u JOIN %T s ON u.phid = s.userPHID
	AND s.type LIKE %> AND s.sessionKey = %s',
	$user->getTableName(),
	'phabricator_session',
	'web-',
	$phsid);
	if ($info) {
	$user->loadFromArray($info);
	}
	}

	$translation = $user->getTranslation();
	if ($translation &&
	$translation != PhabricatorEnv::getEnvConfig('translation.provider')) {
	$translation = newv($translation, array());
	PhutilTranslator::getInstance()
	->setLanguage($translation->getLanguage())
	->addTranslations($translation->getTranslations());
	}

	$request->setUser($user);

	if ($user->getIsDisabled() && $this->shouldRequireEnabledUser()) {
	$disabled_user_controller = new PhabricatorDisabledUserController(
	$request);
	return $this->delegateToController($disabled_user_controller);
	}

	+ $event = new PhabricatorEvent(
	+ PhabricatorEventType::TYPE_CONTROLLER_CHECKREQUEST,
	+ array(
	+ 'request' => $request,
	+ 'controller' => get_class($this),
	+ ));
	+ $event->setUser($user);
	+ PhutilEventEngine::dispatchEvent($event);
	+ $checker_controller = $event->getValue('controller');
	+ if ($checker_controller != get_class($this)) {
	+ return $this->delegateToController($checker_controller);
	+ }
	+
	if (PhabricatorEnv::getEnvConfig('darkconsole.enabled')) {
	if ($user->getConsoleEnabled() \|\|
	PhabricatorEnv::getEnvConfig('darkconsole.always-on')) {
	$console = new DarkConsoleCore();
	$request->getApplicationConfiguration()->setConsole($console);
	}
	}

	if ($this->shouldRequireLogin() && !$user->getPHID()) {
	$login_controller = new PhabricatorLoginController($request);
	return $this->delegateToController($login_controller);
	}

	if ($this->shouldRequireEmailVerification()) {
	$email = $user->loadPrimaryEmail();
	if (!$email) {
	throw new Exception(
	"No primary email address associated with this account!");
	}
	if (!$email->getIsVerified()) {
	$verify_controller = new PhabricatorMustVerifyEmailController($request);
	return $this->delegateToController($verify_controller);
	}
	}

	if ($this->shouldRequireAdmin() && !$user->getIsAdmin()) {
	return new Aphront403Response();
	}

	}

	public function buildStandardPageView() {
	$view = new PhabricatorStandardPageView();
	$view->setRequest($this->getRequest());
	$view->setController($this);

	if ($this->shouldRequireAdmin()) {
	$view->setIsAdminInterface(true);
	}

	return $view;
	}

	public function buildStandardPageResponse($view, array $data) {
	$page = $this->buildStandardPageView();
	$page->appendChild($view);
	$response = new AphrontWebpageResponse();
	$response->setContent($page->render());
	return $response;
	}

	public function getApplicationURI($path = '') {
	if (!$this->getCurrentApplication()) {
	throw new Exception("No application!");
	}
	return $this->getCurrentApplication()->getBaseURI().ltrim($path, '/');
	}

	public function buildApplicationPage($view, array $options) {
	$page = $this->buildStandardPageView();

	$application = $this->getCurrentApplication();
	if ($application) {
	$page->setApplicationName($application->getName());
	$page->setTitle(idx($options, 'title'));
	if ($application->getTitleGlyph()) {
	$page->setGlyph($application->getTitleGlyph());
	}
	}

	if (!($view instanceof AphrontSideNavFilterView)) {
	$nav = new AphrontSideNavFilterView();
	$nav->appendChild($view);
	$view = $nav;
	}

	if ($application) {
	$view->setCurrentApplication($application);
	}

	$view->setUser($this->getRequest()->getUser());
	$view->setFlexNav(true);
	$view->setShowApplicationMenu(true);

	$page->appendChild($view);

	if (idx($options, 'device')) {
	$page->setDeviceReady(true);
	$view->appendChild($page->renderFooter());
	}

	$response = new AphrontWebpageResponse();
	return $response->setContent($page->render());
	}

	public function didProcessRequest($response) {
	$request = $this->getRequest();
	$response->setRequest($request);
	if ($response instanceof AphrontDialogResponse) {
	if (!$request->isAjax()) {
	$view = new PhabricatorStandardPageView();
	$view->setRequest($request);
	$view->setController($this);
	$view->appendChild(
	'<div style="padding: 2em 0;">'.
	$response->buildResponseString().
	'</div>');
	$response = new AphrontWebpageResponse();
	$response->setContent($view->render());
	return $response;
	} else {
	return id(new AphrontAjaxResponse())
	->setContent(array(
	'dialog' => $response->buildResponseString(),
	));
	}
	} else if ($response instanceof AphrontRedirectResponse) {
	if ($request->isAjax()) {
	return id(new AphrontAjaxResponse())
	->setContent(
	array(
	'redirect' => $response->getURI(),
	));
	}
	}
	return $response;
	}

	protected function getHandle($phid) {
	if (empty($this->handles[$phid])) {
	throw new Exception(
	"Attempting to access handle which wasn't loaded: {$phid}");
	}
	return $this->handles[$phid];
	}

	protected function loadHandles(array $phids) {
	$phids = array_filter($phids);
	$this->handles = $this->loadViewerHandles($phids);
	return $this;
	}

	protected function loadViewerHandles(array $phids) {
	return id(new PhabricatorObjectHandleData($phids))
	->setViewer($this->getRequest()->getUser())
	->loadHandles();
	}

	protected function renderHandlesForPHIDs(array $phids) {
	$items = array();
	foreach ($phids as $phid) {
	$items[] = $this->getHandle($phid)->renderLink();
	}
	return implode('<br />', $items);
	}

	}
	diff --git a/src/docs/userguide/events.diviner b/src/docs/userguide/events.diviner
	index e9b7fdb74a..ddf7bff98f 100644
	--- a/src/docs/userguide/events.diviner
	+++ b/src/docs/userguide/events.diviner
	@@ -1,323 +1,339 @@
	@title Events User Guide: Installing Event Listeners
	@group userguide

	Using Phabricator event listeners to customize behavior.

	= Overview =

	Phabricator and Arcanist allow you to install custom runtime event listeners
	which can react to certain things happening (like a Maniphest Task being edited
	or a user creating a new Differential Revision) and run custom code to perform
	logging, synchronize with other systems, or modify workflows.

	These listeners are PHP classes which you install beside Phabricator or
	Arcanist, and which Phabricator loads at runtime and runs in-process. They
	require somewhat more effort upfront than simple configuration switches, but are
	the most direct and powerful way to respond to events.

	= Installing Event Listeners (Phabicator) =

	To install event listeners in Phabricator, follow these steps:

	- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
	- Add it to a libphutil library, or create a new library (for instructions,
	see @{article:libphutil Libraries User Guide}.
	- Configure Phabricator to load the library by adding it to `load-libraries`
	in the Phabricator config.
	- Configure Phabricator to install the event listener by adding the class
	name to `events.listeners` in the Phabricator config.

	You can verify your listener is registered in the "Events" tab of DarkConsole.
	It should appear at the top under "Registered Event Listeners". You can also
	see any events the page emitted there. For details on DarkConsole, see
	@{article:Using DarkConsole}.

	= Installing Event Listeners (Arcanist) =

	To install event listeners in Arcanist, follow these steps:

	- Write a listener class which extends @{class@libphutil:PhutilEventListener}.
	- Add it to a libphutil library, or create a new library (for instructions,
	see @{article:libphutil Libraries User Guide}.
	- Configure Phabricator to load the library by adding it to `load`
	in the Arcanist config (e.g., `.arcconfig`, or user/global config).
	- Configure Arcanist to install the event listener by adding the class
	name to `events.listeners` in the Arcanist config.

	You can verify your listener is registered by running any `arc` command with
	`--trace`. You should see output indicating your class was registered as an
	event listener.

	= Example Listener =

	Phabricator includes an example event listener,
	@{class:PhabricatorExampleEventListener}, which may be useful as a starting
	point in developing your own listeners. This listener listens for a test
	event that is emitted by the script `scripts/util/emit_test_event.php`.

	If you run this script normally, it should output something like this:

	$ ./scripts/util/emit_test_event.php
	Emitting event...
	Done.

	This is because there are no listeners for the event, so nothing reacts to it
	when it is emitted. You can add the example listener by either adding it to
	your `events.listeners` configuration or with the `--listen` command-line flag:

	$ ./scripts/util/emit_test_event.php --listen PhabricatorExampleEventListener
	Installing 'PhabricatorExampleEventListener'...
	Emitting event...
	PhabricatorExampleEventListener got test event at 1341344566
	Done.

	This time, the listener was installed and had its callback invoked when the
	test event was emitted.

	= Available Events =

	You can find a list of all Phabricator events in @{class:PhabricatorEventType}.

	== All Events ==

	The special constant `PhutilEventType::TYPE_ALL` will let you listen for all
	events. Normally, you want to listen only to specific events, but if you're
	writing a generic handler you can listen to all events with this constant
	rather than by enumerating each event.

	== Arcanist Events ==

	Arcanist event constants are listed in @{class@arcanist:ArcanistEventType}.

	All Arcanist events have this data available:

	- `workflow` The active @{class@arcanist:ArcanistBaseWorkflow}.

	== Arcanist: Commit: Will Commit SVN ==

	The constant for this event is `ArcanistEventType::TYPE_COMMIT_WILLCOMMITSVN`.

	This event is dispatched before an `svn commit` occurs and allows you to
	modify the commit message. Data available on this event:

	- `message` The text of the message.

	== Arcanist: Diff: Will Build Message ==

	The constant for this event is `ArcanistEventType::TYPE_DIFF_WILLBUILDMESSAGE`.

	This event is dispatched before an editable message is presented to the user,
	and allows you to, e.g., fill in default values for fields. Data available
	on this event:

	- `fields` A map of field values to be compiled into a message.

	== Arcanist: Diff: Was Created ==

	The constant for this event is `ArcanistEventType::TYPE_DIFF_WASCREATED`.

	This event is dispatched after a diff is created. It is currently only useful
	for collecting timing information. No data is available on this event.

	== Arcanist: Revision: Will Create Revision ==

	The constant for this event is
	`ArcanistEventType::TYPE_REVISION_WILLCREATEREVISION`.

	This event is dispatched before a revision is created. It allows you to modify
	fields to, e.g., edit revision titles. Data available on this event:

	- `specification` Parameters that will be used to invoke the
	`differential.createrevision` Conduit call.

	+== Controller: Check Request ==
	+
	+The constant for this event is
	+`PhabricatorEventType::TYPE_CONTROLLER_CHECKREQUEST`.
	+
	+This event is dispatched when controller is about to begin execution. It is
	+meant for checking if the user is allowed to use the application at the moment.
	+It can check if the user has performed too many operations recently, if his IP
	+address is allowed or if the servers are overloaded to process the request.
	+Data available on this event:
	+
	+- `request` Object of class @{class:AphrontRequest}.
	+- `controller` Class name of the current controller.
	+
	+You can delegate the execution to another controller by modifying `controller`.
	+
	== Maniphest: Will Edit Task ==

	The constant for this event is
	`PhabricatorEventType::TYPE_MANIPHEST_WILLEDITTASK`.

	This event is dispatched before a task is edited, and allows you to respond to
	or alter the edit. Data available on this event:

	- ##task## The @{class:ManiphestTask} being edited.
	- ##transactions## The list of edits (objects of class
	@{class:ManiphestTransaction}) being applied.
	- ##new## A boolean indicating if this task is being created.
	- ##mail## If this edit originates from email, the
	@{class:PhabricatorMetaMTAReceivedMail} object.

	This is similar to the next event (did edit task) but occurs before the edit
	begins.

	== Maniphest: Did Edit Task ==

	The constant for this event is
	`PhabricatorEventType::TYPE_MANIPHEST_DIDEDITTASK`.

	This event is dispatched after a task is edited, and allows you to react to the
	edit. Data available on this event:

	- ##task## The @{class:ManiphestTask} that was edited.
	- ##transactions## The list of edits (objects of class
	@{class:ManiphestTransaction}) that were applied.
	- ##new## A boolean indicating if this task was newly created.
	- ##mail## If this edit originates from email, the
	@{class:PhabricatorMetaMTAReceivedMail} object.

	This is similar to the previous event (will edit task) but occurs after the
	edit completes.

	== Differential: Will Send Mail ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFERENTIAL_WILLSENDMAIL`

	This event is dispatched before Differential sends an email, and allows you to
	edit the message that will be sent. Data available on this event:

	- ##mail## The @{class:PhabricatorMetaMTAMail} being edited.

	== Differential: Will Mark Generated ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFERENTIAL_WILLMARKGENERATED`.

	This event is dispatched before Differential decides if a file is generated (and
	doesn't need to be reviewed) or not. Data available on this event:

	- ##corpus## Body of the file.
	- ##is_generated## Boolean indicating if this file should be treated as
	generated.

	== Diffusion: Did Discover Commit ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFUSION_DIDDISCOVERCOMMIT`.

	This event is dispatched when the daemons discover a commit for the first time.
	This event happens very early in the pipeline, and not all commit information
	will be available yet. Data available on this event:

	- `commit` The @{class:PhabricatorRepositoryCommit} that was discovered.
	- `repository` The @{class:PhabricatorRepository} the commit was discovered
	in.

	== Diffusion: Lookup User ==

	The constant for this event is
	`PhabricatorEventType::TYPE_DIFFUSION_LOOKUPUSER`.

	This event is dispatched when the daemons are trying to link a commit to a
	Phabricator user account. You can listen for it to improve the accuracy of
	associating users with their commits.

	By default, Phabricator will try to find matches based on usernames, real names,
	or email addresses, but this can result in incorrect matches (e.g., if you have
	several employees with the same name) or failures to match (e.g., if someone
	changed their email address). Listening for this event allows you to intercept
	the lookup and supplement the results from another datasource.

	Data available on this event:

	- `commit` The @{class:PhabricatorRepositoryCommit} that data is being looked
	up for.
	- `query` The author or committer string being looked up. This will usually
	be something like "Abraham Lincoln <alincoln@logcabin.example.com>", but
	comes from the commit metadata so it may not be well-formatted.
	- `result` The current result from the lookup (Phabricator's best guess at
	the user PHID of the user named in the "query"). To substitute the result
	with a different result, replace this with the correct PHID in your event
	listener.

	Using @{class@libphutil:PhutilEmailAddress} may be helpful in parsing the query.

	== Edge: Will Edit Edges ==

	NOTE: Edge events are low-level events deep in the core. It is more difficult to
	correct implement listeners for these events than for higher-level events.

	The constant for this event is
	`PhabricatorEventType::TYPE_EDGE_WILLEDITEDGES`.

	This event is dispatched before @{class:PhabricatorEdgeEditor} makes an edge
	edit.

	- `id` An identifier for this edit operation.
	- `add` A list of dictionaries, each representing a new edge.
	- `rem` A list of dictionaries, each representing a removed edge.

	This is similar to the next event (did edit edges) but occurs before the
	edit begins.

	== Edge: Did Edit Edges ==

	The constant for this event is
	`PhabricatorEventType::TYPE_EDGE_DIDEDITEDGES`.

	This event is dispatched after @{class:PhabricatorEdgeEditor} makes an edge
	edit, but before it commits the transactions. Data available on this event:

	- `id` An identifier for this edit operation. This is the same ID as
	the one included in the corresponding "will edit edges" event.
	- `add` A list of dictionaries, each representing a new edge.
	- `rem` A list of dictionaries, each representing a removed edge.

	This is similar to the previous event (will edit edges) but occurs after the
	edit completes.

	== Test: Did Run Test ==

	The constant for this event is
	`PhabricatorEventType::TYPE_TEST_DIDRUNTEST`.

	This is a test event for testing event listeners. See above for details.

	== UI: Did Render Actions ==

	The constant for this event is
	`PhabricatorEventType::TYPE_UI_DIDRENDERACTIONS`.

	This event is dispatched after a @{class:PhabricatorActionListView} is built by
	the UI. It allows you to add new actions that your application may provide, like
	"Fax this Object". Data available on this event:

	- `object` The object which actions are being rendered for.
	- `actions` The current list of available actions.

	NOTE: This event is unstable and subject to change.

	= Debugging Listeners =

	If you're having problems with your listener, try these steps:

	- If you're getting an error about Phabricator being unable to find the
	listener class, make sure you've added it to a libphutil library and
	configured Phabricator to load the library with `load-libraries`.
	- Make sure the listener is registered. It should appear in the "Events" tab
	of DarkConsole. If it's not there, you may have forgotten to add it to
	`events.listeners`.
	- Make sure it calls `listen()` on the right events in its `register()`
	method. If you don't listen for the events you're interested in, you
	won't get a callback.
	- Make sure the events you're listening for are actually happening. If they
	occur on a normal page they should appear in the "Events" tab of
	DarkConsole. If they occur on a POST, you could add a `phlog()`
	to the source code near the event and check your error log to make sure the
	code ran.
	- You can check if your callback is getting invoked by adding `phlog()` with
	a message and checking the error log.
	- You can try listening to `PhutilEventType::TYPE_ALL` instead of a specific
	event type to get all events, to narrow down whether problems are caused
	by the types of events you're listening to.
	- You can edit the `emit_test_event.php` script to emit other types of
	events instead, to test that your listener reacts to them properly. You
	might have to use fake data, but this gives you an easy way to test the
	at least the basics.
	- For scripts, you can run under `--trace` to see which events are emitted
	and how many handlers are listening to each event.

	= Next Steps =

	Continue by:

	- taking a look at @{class:PhabricatorExampleEventListener}; or
	- building a library with @{article:libphutil Libraries User Guide}.
	\ No newline at end of file
	diff --git a/src/infrastructure/events/constant/PhabricatorEventType.php b/src/infrastructure/events/constant/PhabricatorEventType.php
	index 5820ada8f6..c4f2051317 100644
	--- a/src/infrastructure/events/constant/PhabricatorEventType.php
	+++ b/src/infrastructure/events/constant/PhabricatorEventType.php
	@@ -1,47 +1,49 @@
	<?php

	/*
	* Copyright 2012 Facebook, Inc.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	/**
	* For detailed explanations of these events, see
	* @{article:Events User Guide: Installing Event Listeners}.
	*
	* @group events
	*/
	final class PhabricatorEventType extends PhutilEventType {

	+ const TYPE_CONTROLLER_CHECKREQUEST = 'controller.checkRequest';
	+
	const TYPE_MANIPHEST_WILLEDITTASK = 'maniphest.willEditTask';
	const TYPE_MANIPHEST_DIDEDITTASK = 'maniphest.didEditTask';

	const TYPE_DIFFERENTIAL_WILLSENDMAIL = 'differential.willSendMail';
	const TYPE_DIFFERENTIAL_WILLMARKGENERATED = 'differential.willMarkGenerated';

	const TYPE_DIFFUSION_DIDDISCOVERCOMMIT = 'diffusion.didDiscoverCommit';
	const TYPE_DIFFUSION_LOOKUPUSER = 'diffusion.lookupUser';

	const TYPE_EDGE_WILLEDITEDGES = 'edge.willEditEdges';
	const TYPE_EDGE_DIDEDITEDGES = 'edge.didEditEdges';

	const TYPE_TEST_DIDRUNTEST = 'test.didRunTest';

	const TYPE_UI_DIDRENDERACTIONS = 'ui.didRenderActions';

	const TYPE_UI_WILLRENDEROBJECTS = 'ui.willRenderObjects';
	const TYPE_UI_DDIDRENDEROBJECT = 'ui.didRenderObject';
	const TYPE_UI_DIDRENDEROBJECTS = 'ui.didRenderObjects';

	}

File Metadata

Mime Type: text/x-diff
Expires: Thu, May 1, 6:25 PM (1 d, 18 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 109065
Default Alt Text: (23 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions