webino/event-emitter

Event Emitter implementation.

1.1.0 2019-06-21 18:52 UTC

This package is auto-updated.

Last update: 2020-09-18 05:30:22 UTC


README

Event Emitter implementation.

Build Status Coverage Status Code Quality Latest Stable Version

Recommended Usage

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

Setup

PHP from Packagist

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

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.

event lifecycle

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

Build Status Coverage Status Code Quality Latest Unstable Version

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

License Total Downloads GitHub code size in bytes

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.

GitHub issues GitHub forks