phorge / src / docs / user / userguide / events.diviner

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

Using Phorge event listeners to customize behavior.

= Overview =

(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
will continue to remove events in the future.

Phorge 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 Phorge or
Arcanist, and which Phorge 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 (Phorge) =

To install event listeners in Phorge, follow these steps:

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

Phorge 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 Phorge 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:ArcanistWorkflow}.

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

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

== 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 Phorge being unable to find the
    listener class, make sure you've added it to a library and configured
    Phorge 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@contrib:Adding New Classes}.