Last indexed: 7 March 2026 (96fbab)

Event Broadcasting and Anonymous Events

This document describes the mechanisms for broadcasting events to WebSocket clients, focusing on the PendingBroadcast wrapper pattern for event dispatching and the AnonymousEvent class for ad-hoc broadcasting without dedicated event classes. This includes the fluent API for configuring broadcasts, socket exclusion to prevent echoing events back to the originating user, and unique event prevention.

For information about broadcast drivers and connection management, see Broadcasting Architecture and Drivers. For channel authentication and authorization, see Channel Authentication and Authorization.

PendingBroadcast Wrapper Pattern

The PendingBroadcast class wraps event objects and provides a fluent API for configuring how they should be broadcast. It uses PHP's __destruct() magic method to automatically dispatch the event when the object goes out of scope.

Sources: src/broadcasting/src/PendingBroadcast.php1-52 src/broadcasting/src/BroadcastManager.php163-169

The PendingBroadcast constructor accepts an event dispatcher and an event object:

Method	Purpose	Returns
`via(?string $connection)`	Specify which broadcast connection to use	`static`
`toOthers()`	Exclude the current user's socket from receiving the broadcast	`static`
`__destruct()`	Automatically dispatch the event when object is destroyed	`void`

The via() method calls broadcastVia() on the event if the method exists, allowing events to specify their broadcast connection. The toOthers() method calls dontBroadcastToCurrentUser() on the event if available, which sets the socket ID to exclude.

Sources: src/broadcasting/src/PendingBroadcast.php20-42

PendingBroadcast Lifecycle

Sources: src/broadcasting/src/PendingBroadcast.php1-52 src/broadcasting/src/BroadcastManager.php163-169

Anonymous Events

The AnonymousEvent class enables broadcasting without creating a dedicated event class. It provides a fluent API for configuring channels, connection, event name, and payload inline.

Sources: src/broadcasting/src/AnonymousEvent.php1-155 src/broadcasting/src/InteractsWithSockets.php1-36

Creating Anonymous Events

The BroadcastManager provides three factory methods for creating anonymous events:

Sources: src/broadcasting/src/BroadcastManager.php139-158

Method	Purpose	Example
`on(array\|Channel\|string $channels)`	Broadcast to public or mixed channels	`Broadcast::on(['channel1', 'channel2'])`
`private(string $channel)`	Broadcast to a private channel	`Broadcast::private('user.123')`
`presence(string $channel)`	Broadcast to a presence channel	`Broadcast::presence('chat.room')`

Anonymous Event Fluent API

The AnonymousEvent class provides a comprehensive fluent API:

Method	Parameter	Purpose	Returns
`via(string $connection)`	Connection name	Specify broadcast connection (pusher, ably, redis, etc.)	`static`
`as(string $name)`	Event name	Set the event name sent to clients	`static`
`with(array\|Arrayable $payload)`	Event data	Set the payload/data for the event	`static`
`toOthers()`	None	Exclude current user's socket from broadcast	`static`
`send()`	None	Queue the broadcast for async dispatch	`void`
`sendNow()`	None	Broadcast immediately without queueing	`void`

Sources: src/broadcasting/src/AnonymousEvent.php55-117

The with() method automatically converts Arrayable objects (like Eloquent models or collections) to arrays, including nested Arrayable objects:

Sources: src/broadcasting/src/AnonymousEvent.php76-85

Anonymous Event Dispatching

When send() or sendNow() is called, the anonymous event creates a PendingBroadcast and configures it:

Sources: src/broadcasting/src/AnonymousEvent.php100-117

The sendNow() method sets the shouldBroadcastNow flag to true, which causes the event to be dispatched immediately rather than queued. This is implemented through the shouldBroadcastNow() method which is checked during event dispatching:

Sources: src/broadcasting/src/AnonymousEvent.php100-105 src/broadcasting/src/AnonymousEvent.php150-153

Socket Exclusion with toOthers()

The InteractsWithSockets trait provides socket ID tracking to prevent broadcasting events back to the user who triggered them. This is critical for real-time applications where client actions should not echo back to the same client.

Sources: src/broadcasting/src/InteractsWithSockets.php1-36 src/broadcasting/src/BroadcastManager.php129-134

The socket exclusion mechanism works as follows:

The client sends its socket ID in the X-Socket-ID header with each HTTP request
Broadcast::socket() retrieves this header from the current request
When dontBroadcastToCurrentUser() is called, it stores this socket ID
The broadcaster excludes this socket ID when dispatching the event

Method	Purpose	Implementation
`dontBroadcastToCurrentUser()`	Exclude current socket	Sets `$this->socket = Broadcast::socket()`
`broadcastToEveryone()`	Include all sockets	Sets `$this->socket = null`

Sources: src/broadcasting/src/InteractsWithSockets.php9-34

The socket ID is passed to broadcasters in the event payload and used for exclusion:

Sources: src/broadcasting/src/InteractsWithSockets.php19-24 src/broadcasting/src/BroadcastManager.php129-134

Unique Event Prevention

The UniqueBroadcastEvent class wraps events that implement ShouldBeUnique to prevent duplicate broadcasts from being queued. This uses the same unique locking mechanism as unique jobs.

Sources: src/broadcasting/src/UniqueBroadcastEvent.php1-54 src/broadcasting/src/BroadcastManager.php192-211

Unique Event Configuration

The UniqueBroadcastEvent constructor extracts uniqueness configuration from the wrapped event:

Property/Method	Purpose	Default
`uniqueId()` or `$uniqueId`	Unique identifier for the event	`get_class($event)`
`uniqueFor()` or `$uniqueFor`	Lock duration in seconds	None (must be defined)
`uniqueVia()`	Cache store for locks	Default cache store

Sources: src/broadcasting/src/UniqueBroadcastEvent.php26-43

Unique Event Queue Flow

Sources: src/broadcasting/src/BroadcastManager.php174-203 src/broadcasting/src/UniqueBroadcastEvent.php1-54

Event Queuing and Immediate Dispatch

The BroadcastManager::queue() method determines whether to queue an event or dispatch it immediately:

Sources: src/broadcasting/src/BroadcastManager.php174-203

Queue Name Resolution

The queue name is resolved from multiple sources in order of priority:

broadcastQueue() method on the event
$broadcastQueue property on the event
$queue property on the event
null (use default queue)

Sources: src/broadcasting/src/BroadcastManager.php183-189

Immediate Dispatch Logic

Events are dispatched immediately (synchronously) if:

The event implements ShouldBroadcastNow interface, OR
The event has a shouldBroadcastNow() method that returns true

Immediate dispatch uses Dispatcher::dispatchNow() which bypasses the queue:

Sources: src/broadcasting/src/BroadcastManager.php176-181

Complete Usage Examples

Integration with Event System

The broadcasting system integrates with the PSR-14 event dispatcher. When events are dispatched through the event system, listeners can intercept them:

Sources: src/broadcasting/src/PendingBroadcast.php47-50 src/broadcasting/src/BroadcastManager.php174-203

Refresh this wiki

URL: https://deepwiki.com/hypervel/components/8.3-event-broadcasting-and-anonymous-events