Event System

The Event System provides a mechanism for dispatching and listening to application events. It enables loosely coupled communication between different parts of your application through an observer pattern implementation. Events can be simple string identifiers or event objects, and listeners can be closures, class methods, or queued listeners.

For information about broadcasting events to WebSocket channels, see Broadcasting. For testing event dispatching, see Event Testing.

Purpose and Scope

This document covers:

• The Event facade and its integration with PSR-14 EventDispatcherInterface
• Dispatching events with dispatch() and until()
• Registering event listeners with listen() and subscribe()
• Event resolution and wildcard listeners
• Testing events with EventFake

Architecture Overview

The Event System consists of three primary components: the Event facade that provides static access, an underlying EventDispatcher implementation, and the EventFake for testing.

Sources: src/Facades/Event.php1-105 src/Testing/Fakes/EventFake.php1-327

Event Facade

The Event facade provides static access to the event dispatcher registered in the service container. It resolves to EventDispatcherInterface, allowing the underlying implementation to be swapped.

Facade Registration

The facade accessor returns EventDispatcherInterface::class, enabling dependency injection and testability.

Sources: src/Facades/Event.php101-104

Available Methods

Method	Description
dispatch(object|string $event, mixed $payload, bool $halt)	Fire an event and call listeners
until(object|string $event, mixed $payload)	Dispatch until first non-null response
listen(array|string $events, mixed $listener)	Register event listener
subscribe(object|string $subscriber)	Register event subscriber class
push(string $event, mixed $payload)	Register event to dispatch later
flush(string $event)	Flush pushed events
forget(string $event)	Remove event listeners
hasListeners(string $eventName)	Check if event has listeners
getListeners(string $eventName)	Get all listeners for event

Sources: src/Facades/Event.php12-26

Dispatching Events

Events can be dispatched using either event objects or string identifiers. The dispatcher invokes all registered listeners and returns the results.

Basic Event Dispatch

The dispatch() method accepts three parameters:

• $event: Event object or string name
• $payload: Additional data passed to listeners (default: [])
• $halt: Stop after first non-null response (default: false)

Sources: src/Facades/Event.php12

Halting Event Propagation

The until() method dispatches an event and stops at the first listener that returns a non-null value:

Sources: src/Facades/Event.php14

Registering Listeners

Listeners can be registered as closures, class methods, or subscriber classes. The listen() method supports multiple registration patterns.

Listener Registration Flow

Sources: src/Facades/Event.php13 src/Facades/Event.php24

Listener Query Methods

The dispatcher provides methods to inspect registered listeners:

Method	Return Type	Description
hasListeners(string $eventName)	bool	Check if event has any listeners
getListeners(string $eventName)	iterable	Get all listeners for event
getRawListeners()	array	Get all raw listener registrations

Sources: src/Facades/Event.php20 src/Facades/Event.php15 src/Facades/Event.php25

Event Resolution

When an event is dispatched, the dispatcher resolves the event name and invokes all registered listeners in priority order.

Event Name Resolution

Event objects are converted to their fully-qualified class name. String events are used directly as the event name.

Sources: src/Testing/Fakes/EventFake.php231-244

Wildcard Listeners

The event system supports wildcard listeners that match multiple event patterns:

Sources: src/Facades/Event.php21

Deferred and Queued Events

The event system supports deferring event dispatch and queuing listeners for asynchronous processing.

Push and Flush Pattern

Method	Description
push(string $event, mixed $payload)	Register event to dispatch later
flush(string $event)	Dispatch all pushed events of type
forgetPushed()	Clear all pushed events without dispatching

Sources: src/Facades/Event.php16-18

Testing with EventFake

The EventFake class intercepts events during testing, recording dispatched events instead of executing listeners. This enables verification without side effects.

Fake Instantiation Flow

Sources: src/Facades/Event.php45-53

EventFake Interception

The fake determines whether to intercept or dispatch events based on configuration:

Sources: src/Testing/Fakes/EventFake.php231-244 src/Testing/Fakes/EventFake.php249-262

Selective Faking

The EventFake supports selective interception with three modes:

Mode	Method	Behavior
Fake all	Event::fake()	Intercept all events
Fake specific	Event::fake(['user.registered'])	Intercept only listed events
Fake except	Event::fakeExcept(['critical.event'])	Intercept all except listed

Sources: src/Facades/Event.php45-65 src/Testing/Fakes/EventFake.php28-35 src/Testing/Fakes/EventFake.php54-62

Scoped Faking

The facade provides methods to fake events only during a specific callable's execution:

Method	Description
fakeFor(callable $callable, array $events)	Fake events only during callable execution
fakeExceptFor(callable $callable, array $events)	Fake all except specified during callable

Sources: src/Facades/Event.php70-99

Assertion Methods

The EventFake provides assertion methods to verify event dispatching in tests:

Assertion API

Sources: src/Testing/Fakes/EventFake.php100-159 src/Testing/Fakes/EventFake.php164-177

Assertion Method Details

Method	Parameters	Description
assertDispatched(string|Closure, callable|int|null)	Event name/closure, callback/count	Assert event was dispatched
assertNotDispatched(string|Closure, callable|null)	Event name/closure, callback	Assert event was not dispatched
assertDispatchedTimes(string, int)	Event name, expected count	Assert event dispatched exact times
assertListening(string, string)	Event name, listener class	Assert listener attached to event
assertNothingDispatched()	None	Assert no events were dispatched

Sources: src/Facades/Event.php28-35

Closure-Based Assertions

When using a closure as the first argument to assertDispatched() or assertNotDispatched(), the fake extracts the event type from the closure's first parameter type hint:

Sources: src/Testing/Fakes/EventFake.php102-104 src/Testing/Fakes/EventFake.php136-138

Event Storage and Recording

The EventFake stores intercepted events in an internal array keyed by event name, with each entry containing the dispatch arguments.

Recording Structure

Sources: src/Testing/Fakes/EventFake.php39-40 src/Testing/Fakes/EventFake.php236

Listener Verification

The assertListening() method verifies that a specific listener is attached to an event by inspecting the dispatcher's listener registry:

Sources: src/Testing/Fakes/EventFake.php67-95

Delegation to Real Dispatcher

The EventFake implements EventDispatcherInterface and delegates non-interception methods to the real dispatcher:

This ensures that listener registration and queries work normally even when faking, allowing tests to register listeners and verify their attachment.

Sources: src/Testing/Fakes/EventFake.php189-219 src/Testing/Fakes/EventFake.php323-326

Integration with Other Systems

The Event facade integrates with several other systems in the package:

Database Model Events

When Event::fake() is called, it updates the database model event dispatcher:

Sources: src/Facades/Event.php49

Cache Event Dispatcher

The cache manager maintains a reference to the event dispatcher which must be refreshed when swapping:

Sources: src/Facades/Event.php50 src/Facades/Event.php80