Yii Event Dispatcher

1.1.0 2022-10-27 12:02 UTC

This package is auto-updated.

Last update: 2024-02-09 06:37:45 UTC



Yii Event Dispatcher

PSR-14 compatible event dispatcher provides an ability to dispatch events and listen to events dispatched.

Latest Stable Version Total Downloads Build Status Code Coverage Scrutinizer Code Quality Mutation testing badge static analysis type-coverage


  • PSR-14 compatible.
  • Simple and lightweight.
  • Encourages designing event hierarchy.
  • Can combine multiple event listener providers.


  • PHP 8.0 or higher.


The package could be installed with composer:

composer require yiisoft/event-dispatcher --prefer-dist

General usage

The library consists of two parts: event dispatcher and event listener provider. Provider's job is to register listeners for a certain event type. Dispatcher's job is to take an event, get listeners for it from a provider and call them sequentially.

// Add some listeners.
$listeners = (new \Yiisoft\EventDispatcher\Provider\ListenerCollection())
    ->add(function (AfterDocumentProcessed $event) {
        $document = $event->getDocument();
        // Do something with document.

$provider = new Yiisoft\EventDispatcher\Provider\Provider($listeners);
$dispatcher = new Yiisoft\EventDispatcher\Dispatcher\Dispatcher($provider);

The event dispatching may look like:

use Psr\EventDispatcher\EventDispatcherInterface;

final class DocumentProcessor
    private EventDispatcherInterface $eventDispatcher;
    public function __construct(EventDispatcherInterface $eventDispatcher) {
        $this->eventDispatcher = $eventDispatcher;

    public function process(Document $document): void
        // Process the document, then dispatch completion event.
        $this->eventDispatcher->dispatch(new AfterDocumentProcessed($document));

Stoppable events

Event could be made stoppable by implementing Psr\EventDispatcher\StoppableEventInterface:

final class BusyEvent implements Psr\EventDispatcher\StoppableEventInterface
    // ...

    public function isPropagationStopped(): bool
        return true;

This way we can ensure that only first event listener will be able to handle the event. Another option is to allow stopping propagation in one of the listeners by providing corresponding event method.

Events hierarchy

Events do not have any name or wildcard matching on purpose. Event class names and class/interface hierarchy and composition could be used to achieve great flexibility:

interface DocumentEvent

final class BeforeDocumentProcessed implements DocumentEvent

final class AfterDocumentProcessed implements DocumentEvent

With the interface above listening to all document-related events could be done as:

$listeners->add(static function (DocumentEvent $event) {
    // log events here

Combining multiple listener providers

In case you want to combine multiple listener providers, you can use CompositeProvider:

$compositeProvider = new Yiisoft\EventDispatcher\Provider\CompositeProvider();
$provider = new Yiisoft\EventDispatcher\Provider\Provider($listeners);
$compositeProvider->add(new class implements ListenerProviderInterface {
    public function getListenersForEvent(object $event): iterable
        yield static function ($event) {
            // handle 

$dispatcher = new Yiisoft\EventDispatcher\Dispatcher\Dispatcher($compositeProvider);

Register listeners with concrete event names

You may use a more simple listener provider, which allows you to specify which event they can provide.

It can be useful in some specific cases, for instance if one of your listeners does not need the event object passed as a parameter (can happen if the listener only needs to run at a specific stage during runtime, but does not need event data).

In that case, it is advised to use the aggregate (see above) if you need features from both providers included in this library.

$listeners = (new \Yiisoft\EventDispatcher\Provider\ListenerCollection())
    ->add(static function () {
    // this function does not need an event object as argument
}, SomeEvent::class);

Dispatching to multiple dispatchers

There may be a need to dispatch an event via multiple dispatchers at once. It could be achieved like the following:

use Yiisoft\EventDispatcher\Dispatcher\CompositeDispatcher;
use Yiisoft\EventDispatcher\Dispatcher\Dispatcher;
use Yiisoft\EventDispatcher\Provider\ListenerCollection;
use Yiisoft\EventDispatcher\Provider\Provider;

// Add some listeners.
$listeners1 = (new ListenerCollection())
    ->add(function (AfterDocumentProcessed $event) {
        $document = $event->getDocument();
        // Do something with document.

$provider1 = new Provider($listeners1);

// Add some listeners.
$listeners2 = (new ListenerCollection())
    ->add(function (AfterDocumentProcessed $event) {
        $document = $event->getDocument();
        // Do something with document.

$provider2 = new Provider($listeners2);

$dispatcher = new CompositeDispatcher();
$dispatcher->attach(new Dispatcher($provider1));
$dispatcher->attach(new Dispatcher($provider2));

$dispatcher->dispatch(new MyEvent());


Unit testing

The package is tested with PHPUnit. To run tests:


Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:


Static analysis

The code is statically analyzed with Psalm. To run static analysis:



Yii Event Dispatcher is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.


  • Larry Garfield (@crell) for initial implementation of deriving callable parameter type.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack