Event Broadcasting

Purpose and Scope

This document explains how events are prepared for broadcasting, the complete lifecycle from event creation to message delivery, and the various event wrappers and helpers that facilitate this process. It covers the core mechanisms by which application events are transformed into broadcast messages that can be delivered through various broadcasting drivers.

For information about creating standard broadcastable event classes, see Standard Broadcast Events. For ad-hoc broadcasting without formal event classes, see Anonymous Events. For preventing duplicate broadcasts, see Unique Events. For fluent event configuration patterns, see Pending & Deferred Broadcasting.

Event Broadcasting Lifecycle

The event broadcasting system supports multiple execution paths depending on event characteristics. Events can be broadcast immediately, queued for asynchronous processing, or constrained to prevent duplicates.

Lifecycle Flow Diagram

Sources: src/BroadcastManager.php174-203

This diagram illustrates the three primary execution paths in the BroadcastManager::queue() method. The manager determines the appropriate path by inspecting event interfaces and properties, then wraps the event and dispatches it accordingly.

Event Execution Paths

Path	Trigger	Wrapper Class	Execution	Use Case
Immediate	ShouldBroadcastNow interface	BroadcastEvent	Synchronous via dispatchNow()	Time-critical notifications
Standard Queued	ShouldBroadcast interface	BroadcastEvent	Asynchronous via queue	Normal broadcasts
Unique Queued	ShouldBeUnique interface	UniqueBroadcastEvent	Asynchronous with lock	Prevent duplicate processing

Sources: src/BroadcastManager.php176-203 src/BroadcastEvent.php15-16

Event Preparation Requirements

Events must implement specific interfaces and provide certain methods for the broadcasting system to process them correctly. The BroadcastEvent wrapper relies on these methods to extract necessary information.

Required Event Interface

Sources: src/BroadcastEvent.php60-85 src/Contracts/ShouldBroadcastNow.php1-9 src/Contracts/ShouldBeUnique.php1-9

Event Method Reference

Method	Return Type	Required	Purpose	Default Behavior
broadcastOn()	array|Channel	Yes	Defines target channels	None - must be implemented
broadcastAs()	string	No	Overrides event name	Uses fully qualified class name
broadcastWith()	array	No	Defines payload data	Uses all public properties
broadcastConnections()	array	No	Specifies broadcast drivers	Uses default connection
broadcastQueue()	string	No	Sets queue name	Uses queue property or default
shouldBroadcastNow()	bool	No	Forces immediate broadcast	Checks ShouldBroadcastNow interface

Sources: src/BroadcastEvent.php68-76

Event Wrapping Process

The BroadcastManager::queue() method transforms application events into job wrappers that can be queued and processed asynchronously. The wrapping process preserves event data while adding queue configuration.

BroadcastEvent Wrapper

The BroadcastEvent class wraps events implementing ShouldBroadcast and transforms them into queueable jobs. It inherits queue configuration from the original event.

Sources: src/BroadcastEvent.php47-55

The wrapper constructor extracts queue-related properties from the event at src/BroadcastEvent.php50-54:

Property	Source	Purpose
tries	$event->tries	Maximum retry attempts
timeout	$event->timeout	Job execution timeout
backoff	$event->backoff	Retry delay
afterCommit	$event->afterCommit	Wait for database commit
maxExceptions	$event->maxExceptions	Exception threshold

Queue Name Resolution

The BroadcastManager determines the queue name using a priority-based selection mechanism at src/BroadcastManager.php183-188:

Sources: src/BroadcastManager.php183-188

Broadcast Execution

When a BroadcastEvent job is processed by the queue worker, its handle() method orchestrates the actual broadcast through the broadcasting drivers.

Execution Process

The BroadcastEvent::handle() method at src/BroadcastEvent.php60-85 executes the following steps:

1. Channel Resolution: Extracts channels from broadcastOn() method
2. Event Name Determination: Uses broadcastAs() or falls back to class name
3. Connection Selection: Retrieves broadcast connections from event
4. Payload Extraction: Calls broadcastWith() or reflects public properties
5. Broadcasting: Iterates connections and broadcasts to each

Sources: src/BroadcastEvent.php60-85

Payload Extraction Logic

The getPayloadFromEvent() method at src/BroadcastEvent.php90-107 uses two strategies:

Strategy	Condition	Behavior
Custom Payload	broadcastWith() method exists and returns non-null	Uses returned array, merges socket property
Auto-Discovery	No broadcastWith() or returns null	Reflects all public properties, excludes broadcastQueue

The auto-discovery process uses PHP reflection at src/BroadcastEvent.php100-104 to iterate public properties, automatically converting Arrayable instances to arrays through the formatProperty() method.

Sources: src/BroadcastEvent.php90-119

Integration with Queue System

The broadcasting system integrates with the queue system through the BroadcastEvent wrapper, which implements the ShouldQueue interface. This integration enables asynchronous, reliable event processing.

Queue Dispatching Flow

Sources: src/BroadcastManager.php200-202

The BroadcastManager obtains the queue connection at src/BroadcastManager.php200-202 and pushes the wrapped event. The connection name is extracted from the event's connection property, falling back to the default queue connection.

Queue Configuration Inheritance

The BroadcastEvent wrapper inherits configuration from the original event, ensuring queue behavior matches event specifications:

Sources: src/BroadcastEvent.php47-55

This inheritance ensures that queue workers respect the event's intended execution constraints, providing consistent behavior across immediate and queued broadcasts.