Search by

gadwinn / psr-event-dispatcher

Gadwinn

PSR-14 event dispatcher with a priority-aware listener provider.

Package info

github.com/Gadwinn/psr-event-dispatcher

pkg:composer/gadwinn/psr-event-dispatcher

Statistics

Installs: 1

Dependents: 0

Suggesters: 2

Stars: 0

Open Issues: 0

v0.1.0 2026-11-17 15:01 UTC

This package is auto-updated.

Last update: 2026-11-18 11:22:36 UTC


README

A lightweight, strict PSR-14 compliant implementation of EventDispatcherInterface and ListenerProviderInterface, with priority-based listener resolution across the full class and interface hierarchy.

Tech Stack

Installation

composer require gadwinn/psr-event-dispatcher

Usage

1. Create an event

An event is any plain PHP object. To support propagation stopping, implement Psr\EventDispatcher\StoppableEventInterface:

use Psr\EventDispatcher\StoppableEventInterface;

class OrderPlaced implements StoppableEventInterface
{
    private bool $propagationStopped = false;

    public function __construct(public readonly int $orderId) {}

    public function stopPropagation(): void
    {
        $this->propagationStopped = true;
    }

    public function isPropagationStopped(): bool
    {
        return $this->propagationStopped;
    }
}

2. Register listeners

use G\EventDispatcher\ListenerProvider;

$provider = new ListenerProvider();

// Register by exact class name
$provider->addListener(OrderPlaced::class, function (OrderPlaced $event): void {
    echo 'Order #' . $event->orderId . ' placed.';
});

// Register by interface — called for any event implementing that interface
$provider->addListener(StoppableEventInterface::class, function (StoppableEventInterface $event): void {
    // called for every stoppable event
});

// Priority: lower integer = higher priority (default: 0)
$provider->addListener(OrderPlaced::class, $criticalHandler, priority: -10);
$provider->addListener(OrderPlaced::class, $secondaryHandler, priority: 10);

3. Dispatch

use G\EventDispatcher\EventDispatcher;

$dispatcher = new EventDispatcher($provider);

$event = $dispatcher->dispatch(new OrderPlaced(42));

The dispatcher returns the same event object after all listeners have been called. Listeners are invoked synchronously in priority order (ascending integer).

4. Stop propagation

When a listener calls stopPropagation(), the dispatcher checks isPropagationStopped() before each subsequent listener and halts the chain immediately:

$provider->addListener(OrderPlaced::class, function (OrderPlaced $event): void {
    $event->stopPropagation(); // no further listeners will be called
}, priority: -10);

$provider->addListener(OrderPlaced::class, function (OrderPlaced $event): void {
    // never reached
}, priority: 0);

$dispatcher->dispatch(new OrderPlaced(42));

5. Remove a listener

$handler = function (OrderPlaced $event): void { /* ... */ };

$provider->addListener(OrderPlaced::class, $handler, priority: 5);

// Must pass the exact same callable reference and priority
$provider->removeListener(OrderPlaced::class, $handler, priority: 5);

6. Listener resolution — class hierarchy

ListenerProvider resolves listeners registered against the event's own class, all parent classes, and all implemented interfaces. Given:

class SpecialOrder extends OrderPlaced {}

Dispatching SpecialOrder will also invoke listeners registered for OrderPlaced and any shared interfaces, with the full priority ordering applied across all applicable types.

7. Dependency injection

EventDispatcher accepts any Psr\EventDispatcher\ListenerProviderInterface implementation, making it straightforward to inject a custom or composite provider:

use Psr\EventDispatcher\ListenerProviderInterface;

$dispatcher = new EventDispatcher($yourCustomProvider);

License

MIT, see LICENSE.