Overview

A simple library for binding and triggering events.

Installation

Recommended installation is to use composer.

composer require vespula/event

Usage

A simple example:

<?php

use Vespula\Event\EventHandler;

$someObject = new \MysteryObject();
$handler = new EventHandler();

$handler->bind($someObject, 'myEvent', function ($data) {
    echo $data['foo'];
});

// Trigger the event
$data = [
    'foo'=>'bar'
];
$handler->trigger($someObject, 'myEvent', $data);

Bind an event to an object

<?php

use Vespula\Event\EventHandler;

$someObject = new \MysteryObject();
$handler = new EventHandler();

$handler->bind($someObject, 'myEvent', function ($data) {
    echo $data['foo'];
});

Bind an event to an object name (string)

<?php

use Vespula\Event\EventHandler;

$handler = new EventHandler();

$handler->bind(\MysteryObject::class, 'myEvent', function ($data) {
    echo $data['foo'];
});

Binding multiple events using the same event name

You can also register multiple callbacks to the same event and class. These events will be triggered in the order they were bound.

<?php
use Vespula\Event\EventHandler;

$handler = new EventHandler();

$handler->bind($myObject, 'my-event', function ($name) {
    // do some action (log, etc)
});

$handler->bind($myObject, 'my-event', function ($name) {
    // do some other action
});

Callback arguments

You can pass as many arguments to your callback as you like. The last argument will always be the Event object that was triggered.

<?php
$handler->bind($myObject, 'my-event', function ($name, $event) {
    // do some action (log, etc)
    echo $event->getName();
});

Stopping propagation

You can now stop event propagation when you have multiple events under the same target and event name. Remember, the last argument of the callback is the event.

<?php
use Vespula\Event\EventHandler;

$handler->bind($myObject, 'my-event', function ($name) {
    echo "this will fire";
});

$handler->bind($myObject, 'my-event', function ($name, $event) {
    echo "this will fire too";
    $event->stopPropagation();
});

$handler->bind($myObject, 'my-event', function ($name) {
    // This will not fire!
    echo "sad";
});

Unbinding Events

Unbind (remove) an event from the queue. If you pass a callable, you can remove just it from the queue. The callable must be defined as a variable.

<?php
$callback = function() {// do stuff};

$handler->bind($class, 'myevent', $callback);
$handler->unbind($class, 'myevent', $callback);

Adding events with priority

As of version 2, you can now add a 4th argument to the bind() method to indicate the priority of the event callback. This is only useful when you have multiple events under the same event name (see above). Higher numbers take priority. When event callbacks are added with the same priority, they will be called first in, first out (FIFO). The default priority is 0.

<?php
$handler->bind(
    $myObject,
    'my-event',
    function ($name) {
        // This will be first
    },
    10
);

$handler->bind(
    $myObject,
    'my-event',
    function ($name) {
        // this will be next
    },
    4
);

Triggering events

After you have bound events, you can trigger them using the trigger() method.

<?php
$data = ['foo', 'bar'];
$handler->trigger($someObject, 'myEvent', $data);
// OR
$handler->trigger(\MyObject::class, 'myEvent', $data);