Overview

Codacy Badge

A simple library for binding and triggering events.

What's new

2.1.0

  • Add priority to callbacks
  • Stop propagation
  • Unbind events
  • Trait that can be used in any class
  • The event object is passed as the final argument to a callback

Installation

Recommended installation is to use composer.

1
composer require vespula/event

Usage

Bind an event to an object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?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)

1
2
3
4
5
6
7
8
9
<?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.

1
2
3
4
5
6
7
8
<?php
$this->handler->bind($this, 'my-event', function ($name) {
    // do some action (log, etc)
});

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

Callback priority

The event handler uses a modified SplPriorityQueue so you can specify priority on your callbacks. Higher priority means the callback will be triggered earlier. Callbacks with the same priority will be triggered FIFO (first in, first out). The default priority is 0.

1
2
3
4
5
6
<?php
<?php
// Bind with priority 10
$this->handler->bind($this, 'my-event', function ($name) {
    // do some action (log, etc)
}, 10);

Stopping propagation

You can stop event propagation within a callback.

1
2
3
4
5
6
<?php
<?php
$this->handler->bind($this, 'my-event', function ($name, $event) {
    // do some action (log, etc)
    $event->stopPropagation();
});

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.

1
2
3
4
5
6
<?php
<?php
$this->handler->bind($this, 'my-event', function ($name, $event) {
    // do some action (log, etc)
    echo $event->getName();
});

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<?php
$this->handler->bind(
    $this,
    'my-event',
    function ($name) {
        // This will be first
    },
    10
);

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

Triggering events

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

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

Stopping propagation

As of version 2, you can now stop event propagation when you have multiple events under the same target and event name.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<?php
use Vespula\Event\EventHandler;
$this->handler->bind($this, 'my-event', function ($name) {
    echo "this will fire";
});

$this->handler->bind($this, 'my-event', function ($name) {
    echo "this will fire too";
    return EventHandler::STOP_PROPAGATION;
});

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