README

Event Emitter implementation.

Recommended Usage

Use event emitter to decouple routine algorithm from an extended logic.

Setup

composer require webino\event-emitter

Quick Use

Emitting an event:

use Webino\EventEmitter;

$emitter = new EventEmitter;

// registering closure event handler
$emitter->on('example', function () {
    return 'Hello';
});

// emitting custom event
$event = $emitter->emit('example');

/** @var \Webino\EventResults $results */
$results = $event->getResults();

echo $results;

// => Hello

Removing an event handler:

use Webino\EventEmitter;

$emitter = new EventEmitter;

$handler = function () {
    return 'Hello';
};

$emitter->on('example', $handler);

// remove handler for all events
$emitter->off($handler);

// remove all handlers for an event
$emitter->off(null, 'example');

// remove all handlers for all events
$emitter->off();

Emitting an event until:

use Webino\EventEmitter;

$emitter = new EventEmitter;

$emitter->on('example', function () {
    return 'Special';
});

$event = $emitter->emit('example', function ($result) {
    // when result meets required condition
    if ('Special' === $result) {
        // stop propagation
        return false;
    }
    // or continue
    return true;
});

Event handling priority:

use Webino\EventEmitter;

$emitter = new EventEmitter;

$emitter->on('example', function () {
    return 'Begin';
}, $event::BEGIN);

$emitter->on('example', function () {
    return 'Before';
}, $event::BEFORE);

$emitter->on('example', function (Event $event) {
    return 'Main';
}, $event::MAIN);

$emitter->on('example', function () {
    return 'After';
}, $event::AFTER);

$emitter->on('example', function () {
    return 'Finish';
}, $event::FINISH);

// emitting custom event
$event = $emitter->emit('example');

/** @var \Webino\EventResults $results */
$results = $event->getResults();

echo $results;

// => BeginBeforeMainAfterFinish

Event handler:

use Webino\EventEmitter;
use Webino\EventHandlerInterface;
use Webino\EventHandlerTrait;

class ExampleEventHandler implements EventHandlerInterface
{
    use EventHandlerTrait;

    protected function initEvents(): void
    {
        $this->on('example', function () {
            return 'Foo';
        });

        $this->on('example', function () {
            return 'Bar';
        });
    }
}

// emitting custom event
$event = $emitter->emit('example');

/** @var \Webino\EventResults $results */
$results = $event->getResults();

echo $results;

// => FooBar

API

Event

• const BEGIN
  The beginning priority of the event.

• const BEFORE
  Priority before main event.

• const MAIN
  Main event priority.

• const AFTER
  Priority after main event.

• const FINISH
  Priority at the end of the event.

• const OFFSET
  Event priority offset.

• string getName()
  Get event name.

• EventEmitterInterface getTarget()
  Get target object from which event was emitted.

• mixed getValue(string $name, mixed $default = null)
  Get event value by name.

• void setValues(iterable $values)
  Set event values.

• EventResults getResults()
  Returns event results.

• void stop(bool $stop = true)
  Indicate whether or not to stop this event.

• bool isStopped()
  Indicates should stop.

EventEmitter

• void setEventDispatcher(EventDispatcherInterface $dispatcher)
  Inject event dispatcher.

• void on(
  string|EventInterface|EventHandlerInterface $event,
  string|array<int, string>|callable $callback = null,
  int $priority = 1)
  Set event handler.

• void off(callable|EventHandlerInterface $callback = null, string|EventInterface $event = null)
  Remove event handler.

• EventInterface emit(string|EventInterface $event, callable $until = null)
  Invoke handlers.

EventResults

• mixed|null first()
  Returns first response.

• mixed|null last()
  Returns last response.

EventHandler

• void attachEventEmitter(EventDispatcherInterface $emitter)
  Attach event emitter to handler.

• void detachEventEmitter(EventDispatcherInterface $emitter)
  Detach event emitter from handler.

Architecture

It is possible to have a global dispatcher to attach event handlers to.

Event Lifecycle

The basic idea around events is that we just trigger an event and every action happens in handlers, even the main action. Then we can listen to that event using priorities, if we want to act like a middleware. The event propagation could be stopped at any time.

Using events like someEvent.pre and someEvent.post or someEvent.before, someEvent.after, it doesn't matter, is messy and not recommended, don't do that. Give an event a unique name then attach handlers, main action including, using priorities. Convenient way to do that is to use an event priority constants.

Development

Static analysis:

composer analyse

Coding style check:

composer check

Coding style fix:

composer fix

Testing:

composer test

Git pre-commit setup:

ln -s ../../pre-commit .git/hooks/pre-commit

Addendum

Please, if you are interested in this library report any issues and don't hesitate to contribute. We will appreciate any contributions on development of this library.