Basic Concepts

Purpose and Scope

This document introduces the fundamental concepts of the hypervel/event package: events, listeners, the dispatcher, listener provider, the priority system, and the PSR-14 interfaces that underpin the architecture. Understanding these concepts is essential for working with the event system.

For configuration details, see page 1.1. For implementation specifics, see page 2.1 (EventDispatcher) and page 2.2 (ListenerProvider). For asynchronous processing, see page 3.

Events

Events are objects or strings that represent occurrences in your application. They carry information about what happened and trigger listener execution.

Event Types

Type	Description	Example
Object	Any PHP object instance	new UserRegistered($user)
String	Named event with payload	"user.registered" with $payload array

The EventDispatcher::dispatch() method accepts both forms:

Sources: src/Contracts/Dispatcher.php17 src/EventDispatcher.php62

PSR-14 Stoppable Events

Events implementing PSR-14's StoppableEventInterface can halt listener propagation by returning true from isPropagationStopped(). The dispatcher checks this after each listener execution to determine whether to continue processing.

Sources: src/EventDispatcher.php168

Listeners

Listeners are callables that execute when events are dispatched. The system supports multiple listener formats.

Listener Types

Type	Format	Resolution
Closure	function($event) { ... }	Executed directly
Class string	"App\Listeners\SendEmail"	Resolved from container, calls handle() method
Callable array	[Listener::class, 'method']	Class resolved from container
Invokable class	MyListener::class	Resolved from container, calls __invoke()
QueuedClosure	queueable(fn($event) => ...)	Wrapped for async execution

Registration uses the Dispatcher::listen() method:

Sources: src/Contracts/Dispatcher.php22-26 src/EventDispatcher.php116-144

Listener Resolution

When a string or array listener is registered, the EventDispatcher resolves it to a callable:

1. Parse the listener string into [class, method] format
2. Resolve the class from the PSR-11 container
3. Wrap in appropriate execution strategy (immediate, queued, or after-commit)
4. Execute when the event is dispatched

Sources: src/EventDispatcher.php247-282

EventDispatcher

The EventDispatcher class (src/EventDispatcher.php31) is the central coordinator implementing the Dispatcher contract. It manages the entire event lifecycle from dispatch to listener execution.

Core Responsibilities

1. Dispatch events via dispatch() method
2. Query the ListenerProvider for registered listeners
3. Execute listeners in priority order
4. Handle special event types (stoppable, broadcastable, transaction-aware)
5. Return the event object

Dispatch Modes

Mode	Method	Behavior
Standard	dispatch($event)	Executes all listeners
Until	until($event)	Stops at first non-null return
Halt	dispatch($event, [], true)	Stops on false return or stoppable event

Sources: src/EventDispatcher.php62 src/EventDispatcher.php149 src/Contracts/Dispatcher.php17 src/Contracts/Dispatcher.php31

Dispatcher-Provider Relationship

The EventDispatcher depends on a ListenerProvider instance to retrieve listeners:

During dispatch, the dispatcher calls $listeners->getListenersForEvent($event) to retrieve ordered listeners, then executes them sequentially.

Sources: src/EventDispatcher.php49-57 src/EventDispatcher.php205-208

ListenerProvider

The ListenerProvider manages listener storage and retrieval. It implements the PSR-14 ListenerProviderInterface and stores listeners in ListenerData objects.

ListenerData Structure

Each listener is wrapped in a ListenerData object that encapsulates:

Property	Type	Purpose
event	string	Event name or pattern
listener	callable	The listener callable
priority	int	Execution priority (higher = earlier)

Sources: src/ListenerData.php1-22

Priority System

Listeners are executed in priority order, with higher priority values executing first. The system uses SplPriorityQueue internally to maintain ordering.

Default Priority: ListenerData::DEFAULT_PRIORITY (inherited from base class)

When registering listeners, priority can be specified as the third parameter:

Sources: src/EventDispatcher.php119 src/Contracts/Dispatcher.php25 src/ListenerData.php16-21

Listener Retrieval

The provider implements getListenersForEvent() to return listeners for a given event:

This method:

1. Matches the event against registered event names
2. Applies wildcard pattern matching (e.g., "user.*" matches "user.registered")
3. Returns listeners in priority order via internal priority queue

Sources: src/Contracts/ListenerProvider.php14

PSR-14 Compliance

The hypervel/event package implements PSR-14 Event Dispatcher interfaces, ensuring interoperability with other PSR-14 compatible systems.

Interface Implementation

Contract Hierarchy

Sources: src/Contracts/Dispatcher.php12 src/Contracts/ListenerProvider.php9 src/EventDispatcher.php31 src/EventDispatcher.php168

PSR-14 Interface Methods

Interface	Method	Signature
EventDispatcherInterface	dispatch()	dispatch(object $event): object
ListenerProviderInterface	getListenersForEvent()	getListenersForEvent(object $event): iterable
StoppableEventInterface	isPropagationStopped()	isPropagationStopped(): bool

The hypervel/event package extends PSR-14 with additional features like string events, priority ordering, wildcard matching, and transaction awareness while maintaining compatibility with the base standard.

Sources: src/Contracts/Dispatcher.php1-77 src/Contracts/ListenerProvider.php1-40

Event Processing Lifecycle

Dispatch Flow with Code Entities

Sources: src/EventDispatcher.php62-88 src/EventDispatcher.php205-224 src/EventDispatcher.php157-174

Component Architecture

Core Class Relationships

Sources: src/EventDispatcher.php31 src/EventDispatcher.php49-57 src/ListenerData.php9-22 src/Contracts/Dispatcher.php12 src/Contracts/ListenerProvider.php9

Listener Registration Flow

From Registration to Execution

Sources: src/EventDispatcher.php116-144 src/Contracts/ListenerProvider.php19 src/ListenerData.php16-21

Event System Fundamentals

Concept	Purpose	Code Entity	Key Methods
Events	Data objects representing occurrences	Any PHP object or string	N/A
Listeners	Callables that respond to events	Closures, arrays, strings, QueuedClosure	__invoke(), callable
Dispatching	Sending events to listeners	Dispatcher interface	dispatch(), until()
Registration	Adding listeners for events	ListenerProvider interface	on(), listen()
Queuing	Async listener execution	QueuedClosure class	resolve()

Core Interfaces Summary

The system is built around several key contracts that define extensible behavior:

• Dispatcher: Main event dispatching interface extending PSR-14 EventDispatcherInterface
• ListenerProvider: Manages listener registration and retrieval, extending PSR-14 ListenerProviderInterface

These interfaces provide the foundation for the event system's flexibility and framework integration capabilities.

Sources: src/Contracts/Dispatcher.php12 src/Contracts/ListenerProvider.php9