Differential D25007 Diff 23 src/docs/user/userguide/events.diviner

Changeset View

Standalone View

src/docs/user/userguide/events.diviner

@title Events User Guide: Installing Event Listeners		@title Events User Guide: Installing Event Listeners
@group userguide		@group userguide

Using Phabricator event listeners to customize behavior.		Using Phorge event listeners to customize behavior.

= Overview =		= Overview =

(WARNING) The event system is an artifact of a bygone era. Use of the event		(WARNING) The event system is an artifact of a bygone era. Use of the event
system is strongly discouraged. We have been removing events since 2013 and		system is strongly discouraged. We have been removing events since 2013 and
will continue to remove events in the future.		will continue to remove events in the future.

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

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

= Installing Event Listeners (Phabricator) =		= Installing Event Listeners (Phorge) =

To install event listeners in Phabricator, follow these steps:		To install event listeners in Phorge, follow these steps:

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

You can verify your listener is registered in the "Events" tab of DarkConsole.		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		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		see any events the page emitted there. For details on DarkConsole, see
@{article:Using DarkConsole}.		@{article:Using DarkConsole}.

= Installing Event Listeners (Arcanist) =		= Installing Event Listeners (Arcanist) =

To install event listeners in Arcanist, follow these steps:		To install event listeners in Arcanist, follow these steps:

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

You can verify your listener is registered by running any `arc` command with		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		`--trace`. You should see output indicating your class was registered as an
event listener.		event listener.

= Example Listener =		= Example Listener =

Phabricator includes an example event listener,		Phorge includes an example event listener,
@{class:PhabricatorExampleEventListener}, which may be useful as a starting		@{class:PhabricatorExampleEventListener}, which may be useful as a starting
point in developing your own listeners. This listener listens for a test		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`.		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:		If you run this script normally, it should output something like this:

$ ./scripts/util/emit_test_event.php		$ ./scripts/util/emit_test_event.php
Emitting event...		Emitting event...
Show All 9 Lines	your `events.listeners` configuration or with the `--listen` command-line flag:
PhabricatorExampleEventListener got test event at 1341344566		PhabricatorExampleEventListener got test event at 1341344566
Done.		Done.

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

= Available Events =		= Available Events =

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

== All Events ==		== All Events ==

The special constant `PhutilEventType::TYPE_ALL` will let you listen for all		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		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		writing a generic handler you can listen to all events with this constant
rather than by enumerating each event.		rather than by enumerating each event.

▲ Show 20 Lines • Show All 87 Lines • ▼ Show 20 Lines	"Fax this Object". Data available on this event:
- `actions` The current list of available actions.		- `actions` The current list of available actions.

NOTE: This event is unstable and subject to change.		NOTE: This event is unstable and subject to change.

= Debugging Listeners =		= Debugging Listeners =

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

- If you're getting an error about Phabricator being unable to find the		- If you're getting an error about Phorge being unable to find the
listener class, make sure you've added it to a libphutil library and		listener class, make sure you've added it to a libphutil library and
configured Phabricator to load the library with `load-libraries`.		configured Phorge to load the library with `load-libraries`.
- Make sure the listener is registered. It should appear in the "Events" tab		- 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		of DarkConsole. If it's not there, you may have forgotten to add it to
`events.listeners`.		`events.listeners`.
- Make sure it calls `listen()` on the right events in its `register()`		- 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		method. If you don't listen for the events you're interested in, you
won't get a callback.		won't get a callback.
- Make sure the events you're listening for are actually happening. If they		- 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		occur on a normal page they should appear in the "Events" tab of
Show All 21 Lines