README

Minimal PSR-14 event dispatcher with prioritized and composite listener providers. Mutable providers with unsubscribe tokens, immutable dispatcher.

Русская документация

Installation

composer require componenta/event

Requirements

• PHP 8.4+
• psr/event-dispatcher ^1.0

Related Packages

Quick Start

use Componenta\Event\EventDispatcher;
use Componenta\Event\Provider\ListenerProvider;

$provider = new ListenerProvider();
$provider->addListener(UserRegistered::class, fn(UserRegistered $e) => sendWelcomeEmail($e->user));

$dispatcher = new EventDispatcher($provider);
$dispatcher->dispatch(new UserRegistered($user));

Components

EventDispatcher

Final, readonly PSR-14 dispatcher. The provider reference is shared — listeners registered later are visible to all dispatches.

$dispatcher = new EventDispatcher($provider);
$event = $dispatcher->dispatch(new OrderPlaced(...));  // returns the event
$fork  = $dispatcher->withProvider($otherProvider);    // new instance

Events implementing Psr\EventDispatcher\StoppableEventInterface halt propagation when isPropagationStopped() becomes true. An already-stopped event skips all listeners.

ListenerProvider

Plain listener registry keyed by event class. addListener() returns an unsubscribe closure.

$provider = new ListenerProvider();

$off = $provider->addListener(PostPublished::class, $handler);
$off();  // removes the listener

$provider->removeListener(PostPublished::class, $handler);  // bool
$provider->has(PostPublished::class);                       // bool
$provider->contains(PostPublished::class, $handler);        // bool

PrioritizedProvider

Listeners are dispatched in priority order. Sorting is lazy and cache-aware — adding a listener after a dispatch invalidates the cached order.

use Componenta\Event\Provider\PrioritizedProvider;
use Componenta\Event\Provider\SortMode;

$provider = new PrioritizedProvider(mode: SortMode::DESC);   // default
$provider->addListener(CommentPosted::class, $auditHandler, priority: 100);
$provider->addListener(CommentPosted::class, $defaultHandler);  // 0 by default

Priorities are resolved in this order: explicit $priority argument → PrioritizedListenerInterface::$priority → 0. Listeners with equal priority are dispatched in registration order (stable sort).

PrioritizedListenerInterface

Invokable listeners can expose their own priority:

use Componenta\Event\Provider\PrioritizedListenerInterface;

final class LogAuditEvent implements PrioritizedListenerInterface
{
    public int $priority { get => 1000; }

    public function __invoke(AuditEvent $event): void { /* ... */ }
}

$provider->addListener(AuditEvent::class, new LogAuditEvent());  // priority 1000 from interface

CompositeProvider

Aggregates multiple providers into one. contains() is recursive; has() works across EventTypeAwareProviderInterface children.

use Componenta\Event\Provider\CompositeProvider;

$composite = new CompositeProvider([$coreProvider, $moduleProvider]);
$composite->add($pluginProvider);

$dispatcher = new EventDispatcher($composite);

Bulk Registration

$provider->addListeners([
    PostPublished::class => [$sendDigest, $updateIndex],
    CommentPosted::class => $notifyAuthor,
]);

// Prioritized: [callable, int] pairs or bare callables within one group
$prio->addListeners([
    AuditEvent::class => [
        [$rotateLogs,  100],
        [$persistAudit, 50],
        $defaultLogger,        // priority 0 or from interface
    ],
]);

Patterns

One-shot listener

$off = null;
$off = $provider->addListener(Booted::class, function (Booted $e) use (&$off) {
    $off();         // unsubscribe before running (re-entrancy safe)
    initialize($e);
});

Scoped subscription

function withTemporaryListener(ListenerProvider $p, string $event, callable $h, callable $block): mixed
{
    $off = $p->addListener($event, $h);
    try { return $block(); }
    finally { $off(); }
}

Reference

All mutable providers expose: addListener, addListeners, removeListener, contains, has. addListener returns an unsubscribe Closure.

License

MIT