Download the PHP package kuria/event without Composer

Event #####

Event library that implements variations of the mediator and observer patterns.

:depth: 2

Features

• emitting events with any number of arguments
• managing listeners for specific or all events
• ordering listeners by priority
• stopping event propagation
• multiple ways to embed the event system

Requirements

• PHP 7.1+

Components

Event emitter

The EventEmitter class maintains a list of listeners and dispatches events to them.

It is intended to be used as a mediator.

$emitter = new EventEmitter();

EventEmitter implements ObservableInterface.

Observable

The abstract Observable class implements the ObservableInterface using an inner event emitter.

It is intended to be extended by child classes that will emit their own events:

class MyComponent extends Observable { function doSomething() { $this->emit('something'); } }

Alternatively, you can use the ObservableTrait to achieve the same result:

class MyComponent implements ObservableInterface, EventEmitterPropInterface { use ObservableTrait;

// ...

}

Usage

The following applies to both observable as they both implement the ObservableInterface.

Listening to events

Using a callback

To register a callback to be called when a specific event occurs, register it using the on() method. Any event arguments will be passed directly to it.

• the callback can stop event propagation by returning FALSE
• listener priority can be specified using the 3rd argument of on()

To unregister a callback, call the off() method with the same callback (in case of closures this means the same object):

$observable->addListener( new EventListener( 'some.event', function ($arg1, $arg2) {} ) );

• listener priority can be specified by using the 3rd argument of the EventListener constructor
• the callback can stop event propagation by returning FALSE

To unregister a listener, call the removeListener() method with the same event listener object:

class MySubscriber extends EventSubscriber { protected function getListeners(): array { return [ $this->listen('foo.bar', 'onFooBar'), $this->listen('lorem.ipsum', 'onLoremIpsum', 10), $this->listen('dolor.sit', 'onDolorSitA'), $this->listen('dolor.sit', 'onDolorSitB', 5), ]; }

function onFooBar() { / do something / } function onLoremIpsum() { / do something / } function onDolorSitA() { / do something / } function onDolorSitB() { / do something / }

}

$subscriber = new MySubscriber();

Registering the event subscriber:

Unregistering the event subsriber:

Stopping event propagation

Any listener can stop further propagation of the current event by returning FALSE.

This prevents any other listeners from being invoked.

Listener priority

Listener priority determines the order in which the listeners are invoked:

• listeners with greater priority are invoked sooner
• listeners with lesser priority are invoked later
• if the priorities are equal, the order of invocation is undefined
• priority can be negative
• default priority is 0

Listening to all events

To listen to all events, use ObservableInterface::ANY_EVENT in place of the event name:

$observable->on( ObservableInterface::ANY_EVENT, function ($event, $arg1, $arg2) {} );

$observable->addListener( new EventListener( ObservableInterface::ANY_EVENT, function ($event, $arg1, $arg2) {} ) );

• global listeners are invoked before listeners of specific events
• global listeners get an extra event name argument before the emitted event arguments
• global listeners can also stop event propagation by returning FALSE and may have specified listener priority

Emitting events

Events are emitted using the emit() method.

Any extra arguments will be passed to the listeners.

Documenting events

While the event library itself doesn't require this, it is a good idea to explicitly define possible event names and their arguments somewhere.

The example below defines a FieldEvents class for this purpose. Constants of this class are then used in place of event names and their annotations serve as documentation. This also allows for code-completion.

/ @see Field / abstract class FieldEvents { / Emitted when field value is about to be changed. @param Field $field @param mixed $oldValue @param mixed $newValue / const CHANGE = 'change';

/* Emitted when field value is about to be cleared. @param Field $field */ const CLEAR = 'clear';

}

/* @see FieldEvents */ class Field extends Observable { private $name; private $value;

function __construct(string $name, $value = null) { $this->name = $name; $this->value = $value; }

function getName(): string { return $this->name; }

function getValue() { return $this->value; }

function setValue($value): void { $this->emit(FieldEvents::CHANGE, $this, $this->value, $value);

$this->value = $value;

}

function clear() { $this->emit(FieldEvents::CLEAR, $this);

$this->value = null;

}

}

Usage example

Output:

Field 'username' has been changed from '' to 'john.smith'
Field 'username' has been changed from 'john.smith' to 'foo.bar123'
Field 'username' has been cleared