dhii/event-interface

An event standard to complement PSR-14

v0.4.0-alpha1 2021-06-01 18:20 UTC

Requires

• php: ^7.2 | ^8.0
• psr/event-dispatcher: ^1.0

Requires (Dev)

• dhii/event-dispatcher-interface: ^0.2
• phpunit/phpunit: ^8.0 | ^9.0
• slevomat/coding-standard: ^6.0
• vimeo/psalm: ^4.0

Suggests

• dhii/event-dispatcher-interface: For working with name-based events

MIT

• Dhii Team
• Anton Ukhanev

README

Details

The PSR-14 standard provides interfaces used for dispatching events. But what of events themselves? How can a consumer of the dispatcher (i.e. the emitter) interoperate with the handler, if they have no agreement on what an event may look like? This package aims to provide interfaces that could facilitate the interoperability of events that are identified by event name.

Usage

Basic Features

In essence, an event is but a map of parameters associated with a name.

<?php
use Dhii\Events\Event\StoppableEventFactoryInterface;

/* @var $factory StoppableEventFactoryInterface */
$event = $factory->make('my_event', ['key' => 'value']);
echo $event->getName(); // 'my_event'
echo $event->getParam('key'); //  'value'

$params = $event->getParams();
var_dump($params); // ['key' => 'value']

$params['hello'] = 'world';
$event->setParams($params);
echo $event->getParam('hello'); // 'world'
?>

With PSR-14

Events cam be dispatched using a standards-compliant event dispatcher. This example requires the suggested dhii/event-dispatcher-interface package.

<?php
use Psr\EventDispatcher\EventDispatcherInterface;
use Dhii\Events\Event\EventInterface;
use Dhii\Events\Event\StoppableEventFactoryInterface;
use Dhii\Events\Listener\AddListenerCapableInterface;

/* @var $dispatcher EventDispatcherInterface */
/* @var $factory StoppableEventFactoryInterface */
/* @var $listenerMap AddListenerCapableInterface */

// First listener will change a value and stop propagation
$listenerMap->addListener('my_event', function (EventInterface $event) {
    $params = $event->getParams();
    $params['key'] = 'other_value';
    $event->setParams($params);
    $event->stopPropagation();
}, 1);

// Second listener is never run, therefore the value does not change again
$listenerMap->addListener('my_event', function (EventInterface $event) {
    $params = $event->getParams();
    $params['key'] = 'yet another value';
    $event->setParams($params);
}, 2);

$event = $factory->make('my_event', ['key' => 'value']);
$dispatcher->dispatch($event);
echo $event->getParam('key'); // 'other_value'
?>