README

This is a simple PSR-14 event dispatcher, it allows registering callbacks as event listeners. It also supports stoppable events from psr and has listener providers that allow setting priority for listeners or using multiple listener providers at the same time.

Installation

The best way to install Event Dispatcher is via Composer. Just add konecnyjakub/event-dispatcher to your dependencies.

Quick start

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addListener(MyEvent::class, function (MyEvent $event) {
    echo "Event triggered\n";
});
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

Advanced usage

Registering multiple listeners at once

It is possible to register multiple listeners at the same time in PriorityListenerProvider, just pass an array/iterable of arrays into method addListeners.

declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addListeners(MyEvent::class, ["time", "pi", ]);
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

Priority for listeners

The default listener provider supports setting priority for listeners, listeners with higher priority are triggered before those with lower priority. Example:

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addListener(MyEvent::class, "time", 0);
$listenerProvider->addListener(MyEvent::class, "pi", 1);
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

In the example, function pi is called before function time.

It also possible to register multiple listeners with the same priority at the same time, just use method addListeners.

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addListeners(Event::class, ["pi", "time", ], 0);
$listenerProvider->addListener(Event::class, "getdate", 1);
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

The listener provider provides constants PRIORITY_HIGH, PRIORITY_NORMAL and PRIORITY_LOW that can be used for parameter priority of methods addListener/addListeners.

Multiple listener providers

If you need to use multiple listener providers at the same time, just use ChainListenerProvider.

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\ChainListenerProvider;
use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$listenerProvider = new ChainListenerProvider();
$provider1 = new PriorityListenerProvider();
$provider1->addListener(MyEvent::class, "time");
$provider2 = new PriorityListenerProvider();
$provider2->addListener(MyEvent::class, "pi");
$listenerProvider->addProvider($provider1);
$listenerProvider->addProvider($provider2);
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

Stoppable events

The provided event dispatcher supports stoppable events (as defined in psr). We even provide trait TStoppableEvent which you can use in your event classes.

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;
use Konecnyjakub\EventDispatcher\TStoppableEvent;

class MyEvent {
    use TStoppableEvent;
}

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addListener(MyEvent::class, function (MyEvent $event) {
    echo "Event triggered\n";
    $event->stopPropagation();
});
$listenerProvider->addListener(MyEvent::class, "time");
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

Event subscribers

An alternative way to register listeners, is to use event subscribers. An event subscriber is an object which names methods from the same class that listen to a named event. They have to implement the Konecnyjakub\EventDispatcher\IEventSubscriber interface and are added to ListenerProvider or PriorityListenerProvider via method addSubscriber.

The method getSubscribedEvents has to return an array or a traversable object in which the key is a class name (the event's name) and the value is an array of listeners. Each listener is again an array where first value is name of a method of the same class and second value can be a priority for that listener (it is of course taken into account only by PriorityListenerProvider).

<?php
declare(strict_types=1);

use Konecnyjakub\EventDispatcher\EventDispatcher;
use Konecnyjakub\EventDispatcher\PriorityListenerProvider;

class MyEvent {

}

$eventSubscriber = new class implements IEventSubscriber
{
    public function one(): void
    {
    }
    
    public function two(): void
    {
    }
    
    public static function getSubscribedEvents(): iterable
    {
        return [
            Event::class => [
                ["one", ], ["two", 1, ],
            ]
        ];
    }
};

$listenerProvider = new PriorityListenerProvider();
$listenerProvider->addSubscriber($eventSubscriber);
$eventDispatcher = new EventDispatcher($listenerProvider);
$eventDispatcher->dispatch(new MyEvent());

In the example method two is called before method one.

Debugging dispatched events

If you want to debug dispatched events, you can use included DebugEventDispatcher. Its constructor takes an event dispatcher (to which dispatching events is delegated) and a PSR-3 logger which is used to log relevant info.

Currently it only logs that an event was dispatched.

It can also tell you if an event of a certain type of dispatched, just use method dispatched with a class name. You can also specify with second optional parameter how many times it should have been dispatched.

For an example of usage, see tests of the class.

konecnyjakub / event-dispatcher

Maintainers

Details