This is not "just this" of course, as Rocketeer does some magic on the second argument so that Rocketeer::before('deploy', 'composer install') transforms composer install into an actual Task class the Events Dispatcher can call. But in its concept, it's just your basic Dispatcher (or Observer if you like) system.

Registering events

First of all, you can register events in any file that is autoloaded by Composer. If you're using the Rocketeer archive and have no particular autoloading, Rocketeer will by default try to load .rocketeer/events.php or if you have more events and want to split them in multiple files, it'll autoload every file in a .rocketeer/events/* folder.

Listening to events

All tasks in Rocketeer fire two basic events : before and after on which you can hook. But some tasks fire internal events, during their execution, allowing you to execute actions at various points in their lifetime. To listen to these events, there are two methods you can use. Say you want to execute something before the Deploy task symlinks the current folder to the latest release :

You don't need to namespace your events, as Rocketeer will do it for you. It will first namespace all events in the rocketeer. space, then add a slug of the current task, so the two events above would be fired as rocketeer.my-task.making-coffee and rocketeer.my-task.drinking-coffee:

Rocketeer::listenTo('my-task.drinking-coffee','ls');

Now, you can also fire events in Closure Tasks, by you will need to manually namespace those : as all Closure Tasks are at their core anonymous functions, they're anonymous tasks as well which means all events will get fired in rocketeer.closure :

Rocketeer::after('deploy',function($task){$task->fireEvent('some-event'); // Will get fired as rocketeer.closure.some-event
});

This is not a problem per se but can get problematic if you have a lot of Closure Tasks.

Firing events in a particular order

As the events system use illuminate/events, it inherits its priority methods. That means that for every method that adds listeners to an event, you can specify a priority for these listeners. Simple example :

Rocketeer::after('deploy',function($task){$task->campfire->notify('New version deployed on the server');});
Rocketeer::after('deploy',['npm install','grunt']);

Now ideally you'd want your chat room on Campfire to be notified about the deployment only when the NPM packages are installed and Grunt has run its course, because an error might happen there. For this you add a priority at the end of the call : priority is a basic integer, listeners with lowest priority will be fired at the end, and vice versa. So to make sure our Campfire notification would get sent at really the very end of all our listeners, we can just do this :

Rocketeer::after('deploy',function($task){$task->campfire->notify('New version deployed on the server');},-10);
Rocketeer::after('deploy',function($task){$task->runForCurrentRelease(['npm install','grunt']);});

Halting the queue in an event

Whenever an event returns a strict false, Rocketeer will recognize it and halt the whole queue. This is useful to do checks before certain major events and cancel per example deployment if some conditions are not met.

Whatever you use, Rocketeer will display an additional error message stating the queue was canceled and by what Task.

Available events

All tasks have, by default, a before and after events, so do all strategies. Per example the Deploy task will respectively call the following strategies: CreateRelease, Dependencies, Test and Migrate.
That means you can, in the case of a deployment, hook yourself on the following events: