1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-09 16:32:39 +01:00

Add an example event listener, improve documentation, and add a commit discovery event

Summary: Improve documentation around Phabricator events.

Test Plan: Generated and read documentation. Ran test script.

Reviewers: btrahan, jungejason

Reviewed By: jungejason

CC: aran

Maniphest Tasks: T1092

Differential Revision: https://secure.phabricator.com/D2917
This commit is contained in:
epriestley 2012-07-03 16:46:27 -07:00
parent 61b79b5359
commit ddf67fce58
8 changed files with 322 additions and 10 deletions

View file

@ -0,0 +1,57 @@
#!/usr/bin/env php
<?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.
*/
$root = dirname(dirname(dirname(__FILE__)));
require_once $root.'/scripts/__init_script__.php';
$args = new PhutilArgumentParser($argv);
$args->setTagline('emit a test event');
$args->setSynopsis(<<<EOHELP
**emit_test_event.php** [--listen listener] ...
Emit a test event after installing any specified __listener__s.
EOHELP
);
$args->parseStandardArguments();
$args->parse(
array(
array(
'name' => 'listen',
'param' => 'listener',
'repeat' => true,
),
));
$console = PhutilConsole::getConsole();
foreach ($args->getArg('listen') as $listener) {
$console->writeOut("Installing '%s'...\n", $listener);
newv($listener, array())->register();
}
$console->writeOut("Emitting event...\n");
PhutilEventEngine::dispatchEvent(
new PhabricatorEvent(
PhabricatorEventType::TYPE_TEST_DIDRUNTEST,
array(
'time' => time(),
)));
$console->writeOut("Done.\n");
exit(0);

View file

@ -632,6 +632,7 @@ phutil_register_library_map(array(
'PhabricatorEvent' => 'infrastructure/events/PhabricatorEvent.php',
'PhabricatorEventEngine' => 'infrastructure/events/PhabricatorEventEngine.php',
'PhabricatorEventType' => 'infrastructure/events/constant/PhabricatorEventType.php',
'PhabricatorExampleEventListener' => 'infrastructure/events/PhabricatorExampleEventListener.php',
'PhabricatorFeedBuilder' => 'applications/feed/builder/PhabricatorFeedBuilder.php',
'PhabricatorFeedConstants' => 'applications/feed/constants/PhabricatorFeedConstants.php',
'PhabricatorFeedController' => 'applications/feed/controller/PhabricatorFeedController.php',
@ -1647,9 +1648,12 @@ phutil_register_library_map(array(
'PhabricatorErrorExample' => 'PhabricatorUIExample',
'PhabricatorEvent' => 'PhutilEvent',
'PhabricatorEventType' => 'PhutilEventType',
'PhabricatorExampleEventListener' => 'PhutilEventListener',
'PhabricatorFeedController' => 'PhabricatorController',
'PhabricatorFeedDAO' => 'PhabricatorLiskDAO',
'PhabricatorFeedPublicStreamController' => 'PhabricatorFeedController',
'PhabricatorFeedQuery' => 'PhabricatorIDPagedPolicyQuery',
'PhabricatorFeedStory' => 'PhabricatorPolicyInterface',
'PhabricatorFeedStoryAggregate' => 'PhabricatorFeedStory',
'PhabricatorFeedStoryAudit' => 'PhabricatorFeedStory',
'PhabricatorFeedStoryCommit' => 'PhabricatorFeedStory',

View file

@ -374,6 +374,15 @@ final class PhabricatorRepositoryPullLocalDaemon
}
$this->setCache($repository, $commit_identifier);
PhutilEventEngine::dispatchEvent(
new PhabricatorEvent(
PhabricatorEventType::TYPE_DIFFUSION_DIDDISCOVERCOMMIT,
array(
'repository' => $repository,
'commit' => $commit,
)));
} catch (AphrontQueryDuplicateKeyException $ex) {
$commit->killTransaction();
// Ignore. This can happen because we discover the same new commit

View file

@ -9,12 +9,68 @@ Phabricator allows you to install custom runtime event listeners which can react
to certain things happening (like a Maniphest Task being edited) and run custom
code to perform logging, synchronize with other systems, or modify workflows.
NOTE: This feature is new and experimental, so few events are available and
things might not be completely stable.
These listeners are PHP classes which you install beside Phabricator, and which
Phabricator loads at runtime and runs in-process. They are the most direct and
powerful way to respond to events.
= Installing Event Listeners =
To install event listeners, follow these steps:
- Write a listener class which extends @{class: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}.
= 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 =
== PhabricatorEventType::TYPE_MANIPHEST_WILLEDITTASK ==
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.
== 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:
@ -26,14 +82,41 @@ or alter the edit. Data available on this event:
- ##mail## If this edit originates from email, the
@{class:PhabricatorMetaMTAReceivedMail} object.
== PhabricatorEventType::TYPE_DIFFERENTIAL_WILLSENDMAIL ==
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.
== PhabricatorEventType::TYPE_DIFFERENTIAL_WILLMARKGENERATED ==
== 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:
@ -41,3 +124,92 @@ 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.
== 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.
= 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.
= Next Steps =
Continue by:
- taking a look at @{class:PhabricatorExampleEventListener}; or
- building a library with @{article:@{article:libphutil Libraries User Guide}.

View file

@ -16,6 +16,10 @@
* limitations under the License.
*/
/**
* @group events
*/
final class PhabricatorEvent extends PhutilEvent {
private $user;

View file

@ -16,6 +16,9 @@
* limitations under the License.
*/
/**
* @group events
*/
final class PhabricatorEventEngine {
public static function initialize() {

View file

@ -0,0 +1,52 @@
<?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.
*/
/**
* Example event listener. For details about installing Phabricator event hooks,
* refer to @{article:Events User Guide: Installing Event Listeners}.
*
* @group events
*/
final class PhabricatorExampleEventListener extends PhutilEventListener {
public function register() {
// When your listener is installed, its register() method will be called.
// You should listen() to any events you are interested in here.
$this->listen(PhabricatorEventType::TYPE_TEST_DIDRUNTEST);
}
public function handleEvent(PhutilEvent $event) {
// When an event you have called listen() for in your register() method
// occurs, this method will be invoked. You should respond to the event.
// In this case, we just echo a message out so the event test script will
// do something visible.
$console = PhutilConsole::getConsole();
$console->writeOut(
"PhabricatorExampleEventListener got test event at %d\n",
$event->getValue('time'));
}
}

View file

@ -16,14 +16,25 @@
* 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_MANIPHEST_WILLEDITTASK = 'maniphest.willEditTask';
const TYPE_MANIPHEST_DIDEDITTASK = 'maniphest.didEditTask';
const TYPE_DIFFERENTIAL_WILLSENDMAIL = 'differential.willSendMail';
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_EDGE_WILLEDITEDGES = 'edge.willEditEdges';
const TYPE_EDGE_DIDEDITEDGES = 'edge.didEditEdges';
const TYPE_DIFFUSION_DIDDISCOVERCOMMIT = 'diffusion.didDiscoverCommit';
const TYPE_EDGE_WILLEDITEDGES = 'edge.willEditEdges';
const TYPE_EDGE_DIDEDITEDGES = 'edge.didEditEdges';
const TYPE_TEST_DIDRUNTEST = 'test.didRunTest';
}