inanepain/event

PSR-14 implementation: event dispatcher.

0.1.0 2022-07-26 17:04 UTC

Requires

• psr/event-dispatcher: ^1.0

UNLICENSE

• Philip Michael Raab

• php
• event
• dispatcher
• listener
• inane

README

Table of Contents

• inanepain/event
• 1. Install
• 2. Usage
  • 2.1. Events
    • 2.1.1. Event
    • 2.1.2. StoppableEvent
  • 2.2. Dispatcher
    • 2.2.1. EventDispatcher
    • 2.2.2. Listener Providers
  • 2.3. Listener Providers
    • 2.3.1. Default Provider
    • 2.3.2. Prioritised Provider
    • 2.3.3. Randomized Provider
    • 2.3.4. Aggregate Provider

inanepain/event

PSR-14 implementation: event dispatcher.

1. Install

composer

composer require inanepain/event

2. Usage

2.1. Events

2.1.1. Event

Inane\Event\Event

Base event class. Extend this to create custom events.

Properties

name : string

The event name. Defaults to the fully-qualified class name of the event if not explicitly set.

Usage

use Inane\Event\Event;

// Use directly
$event = new Event();
echo $event->name; // "Inane\Event\Event"

// Extend to create a named domain event
class UserRegistered extends Event {
    public function __construct(
        public readonly string $username
    ) {}
}

$event = new UserRegistered('alice');
echo $event->name;     // "UserRegistered"
echo $event->username; // "alice"

2.1.2. StoppableEvent

Inane\Event\StoppableEvent

Extends Event and implements StoppableEventInterface. Allows event propagation to be halted mid-dispatch; once stopped, propagation cannot be resumed.

Properties

propagationStopped : bool

Whether propagation has been stopped. Once set to true it cannot be reset to false.

Methods

isPropagationStopped() : bool

Returns true if propagation has been stopped.

stopPropagation() : void

Stops propagation of the event to further listeners.

Usage

use Inane\Event\StoppableEvent;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\ListenerProvider;

class Odd extends StoppableEvent {
    public function __construct(
        public readonly string $message = ''
    ) {}
}

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Odd::class, function (Odd $event) {
    echo "Listener 1: " . $event->message . "\n";
    if ($event->message > 5) $event->stopPropagation();
});

$provider->addListener(Odd::class, function (Odd $event) {
    echo "Listener 2: " . $event->message . "\n";
});

$dispatcher->dispatch(new Odd('3')); // both listeners fire
$dispatcher->dispatch(new Odd('7')); // only listener 1 fires

2.2. Dispatcher

2.2.1. EventDispatcher

Inane\Event\EventDispatcher

Implements EventDispatcherInterface. Dispatches events to all registered listeners via a ListenerProviderInterface. Respects StoppableEventInterface — propagation halts as soon as isPropagationStopped() returns true.

Constructor

__construct(ListenerProviderInterface $provider)

Accepts any listener provider implementing ListenerProviderInterface.

Methods

dispatch(object $event) : object

Dispatches the event to all applicable listeners and returns the (possibly modified) event.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\ListenerProvider;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, function (Event $event) {
    echo "Received: " . $event->name . "\n";
});

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

2.2.2. Listener Providers

Default Provider

Inane\Event\Provider\ListenerProvider

Basic listener provider. Listeners are registered per event class name and returned in the order they were added.

Methods

addListener(string|object $event, callable $listener) : static

Registers a listener for the given event class name or instance. Returns the provider for chaining.

getListenersForEvent(object $event) : iterable

Returns all listeners registered for the event’s class, in insertion order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\ListenerProvider;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("First\n"))
         ->addListener(Event::class, fn (Event $e) => print("Second\n"));

$dispatcher->dispatch(new Event());
// First
// Second

Prioritised Provider

Inane\Event\Provider\PrioritisedListenerProvider

Listener provider that dispatches listeners in priority order. Higher priority values are called first; listeners with equal priority are called in insertion order.

Methods

addListener(string|object $event, callable $listener, int $priority = 0) : static

Registers a listener with an optional priority (default 0). Returns the provider for chaining.

getListenersForEvent(object $event) : iterable

Returns listeners ordered by descending priority.

clearListeners(string|object $event) : void

Removes all listeners registered for the given event.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\PrioritisedListenerProvider;

$provider = new PrioritisedListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("Low\n"),    priority: -10)
         ->addListener(Event::class, fn (Event $e) => print("Default\n"))
         ->addListener(Event::class, fn (Event $e) => print("High\n"),   priority: 10);

$dispatcher->dispatch(new Event());
// High
// Default
// Low

Randomized Provider

Inane\Event\Provider\RandomizedListenerProvider

Extends ListenerProvider. Returns listeners in a randomised order on each dispatch. Useful for testing that application behaviour does not depend on listener execution order.

Methods

Inherits addListener() from ListenerProvider.

getListenersForEvent(object $event) : iterable

Returns all listeners for the event in a randomised order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\RandomizedListenerProvider;

$provider = new RandomizedListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("A\n"))
         ->addListener(Event::class, fn (Event $e) => print("B\n"))
         ->addListener(Event::class, fn (Event $e) => print("C\n"));

// Order of A, B, C is random on each dispatch
$dispatcher->dispatch(new Event());

Aggregate Provider

Inane\Event\Provider\AggregateProvider

Combines multiple listener providers into one. Each sub-provider is queried in the order it was added; all listeners from the first provider are returned before any from the second, and so on. Per-provider internal ordering is preserved, but cross-provider ordering is not guaranteed.

Methods

addProvider(ListenerProviderInterface $provider) : static

Appends a provider to the aggregate. Returns the aggregate for chaining.

getListenersForEvent(object $event) : iterable

Yields listeners from each sub-provider in registration order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\AggregateProvider;
use Inane\Event\Provider\ListenerProvider;
use Inane\Event\Provider\PrioritisedListenerProvider;

$basic      = new ListenerProvider();
$prioritized = new PrioritisedListenerProvider();

$basic->addListener(Event::class, fn (Event $e) => print("Basic listener\n"));
$prioritized->addListener(Event::class, fn (Event $e) => print("Priority listener\n"), priority: 5);

$aggregate = new AggregateProvider();
$aggregate->addProvider($basic)
          ->addProvider($prioritized);

$dispatcher = new EventDispatcher($aggregate);
$dispatcher->dispatch(new Event());
// Basic listener
// Priority listener

2.3. Listener Providers

2.3.1. Default Provider

Inane\Event\Provider\ListenerProvider

Basic listener provider. Listeners are registered per event class name and returned in the order they were added.

Methods

addListener(string|object $event, callable $listener) : static

Registers a listener for the given event class name or instance. Returns the provider for chaining.

getListenersForEvent(object $event) : iterable

Returns all listeners registered for the event’s class, in insertion order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\ListenerProvider;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("First\n"))
         ->addListener(Event::class, fn (Event $e) => print("Second\n"));

$dispatcher->dispatch(new Event());
// First
// Second

2.3.2. Prioritised Provider

Inane\Event\Provider\PrioritisedListenerProvider

Listener provider that dispatches listeners in priority order. Higher priority values are called first; listeners with equal priority are called in insertion order.

Methods

addListener(string|object $event, callable $listener, int $priority = 0) : static

Registers a listener with an optional priority (default 0). Returns the provider for chaining.

getListenersForEvent(object $event) : iterable

Returns listeners ordered by descending priority.

clearListeners(string|object $event) : void

Removes all listeners registered for the given event.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\PrioritisedListenerProvider;

$provider = new PrioritisedListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("Low\n"),    priority: -10)
         ->addListener(Event::class, fn (Event $e) => print("Default\n"))
         ->addListener(Event::class, fn (Event $e) => print("High\n"),   priority: 10);

$dispatcher->dispatch(new Event());
// High
// Default
// Low

2.3.3. Randomized Provider

Inane\Event\Provider\RandomizedListenerProvider

Extends ListenerProvider. Returns listeners in a randomised order on each dispatch. Useful for testing that application behaviour does not depend on listener execution order.

Methods

Inherits addListener() from ListenerProvider.

getListenersForEvent(object $event) : iterable

Returns all listeners for the event in a randomised order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\RandomizedListenerProvider;

$provider = new RandomizedListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(Event::class, fn (Event $e) => print("A\n"))
         ->addListener(Event::class, fn (Event $e) => print("B\n"))
         ->addListener(Event::class, fn (Event $e) => print("C\n"));

// Order of A, B, C is random on each dispatch
$dispatcher->dispatch(new Event());

2.3.4. Aggregate Provider

Inane\Event\Provider\AggregateProvider

Combines multiple listener providers into one. Each sub-provider is queried in the order it was added; all listeners from the first provider are returned before any from the second, and so on. Per-provider internal ordering is preserved, but cross-provider ordering is not guaranteed.

Methods

addProvider(ListenerProviderInterface $provider) : static

Appends a provider to the aggregate. Returns the aggregate for chaining.

getListenersForEvent(object $event) : iterable

Yields listeners from each sub-provider in registration order.

Usage

use Inane\Event\Event;
use Inane\Event\EventDispatcher;
use Inane\Event\Provider\AggregateProvider;
use Inane\Event\Provider\ListenerProvider;
use Inane\Event\Provider\PrioritisedListenerProvider;

$basic      = new ListenerProvider();
$prioritized = new PrioritisedListenerProvider();

$basic->addListener(Event::class, fn (Event $e) => print("Basic listener\n"));
$prioritized->addListener(Event::class, fn (Event $e) => print("Priority listener\n"), priority: 5);

$aggregate = new AggregateProvider();
$aggregate->addProvider($basic)
          ->addProvider($prioritized);

$dispatcher = new EventDispatcher($aggregate);
$dispatcher->dispatch(new Event());
// Basic listener
// Priority listener