Pending & Deferred Broadcasting

This page documents the PendingBroadcast helper class and its role in providing a fluent, deferred dispatch pattern for broadcast events. It explains how events can be configured before dispatching and covers the distinction between immediate and queued broadcasting patterns.

For information about the event wrapper classes used after dispatch, see Standard Broadcast Events. For unique event broadcasting with duplicate prevention, see Unique Events.

---

Overview

The broadcasting system provides two primary mechanisms for event dispatch timing:

Pattern	Trigger	Use Case
Deferred Broadcasting	Object destruction via __destruct()	Default pattern for configuring events fluently before automatic dispatch
Immediate Broadcasting	Synchronous execution via ShouldBroadcastNow	Events that must be broadcast without queue delay
Queued Broadcasting	Asynchronous via queue system	Default behavior for ShouldBroadcast events without immediate flag

The PendingBroadcast class serves as a fluent wrapper that allows event configuration before the event is dispatched to the event dispatcher, which then triggers the broadcasting system.

---

The PendingBroadcast Helper

Creating Pending Broadcasts

The BroadcastManager provides an event() method that creates a PendingBroadcast instance:

BroadcastManager::event($event) → PendingBroadcast

This method is defined in src/BroadcastManager.php163-169 and returns a new PendingBroadcast wrapper around the provided event.

Sources: src/BroadcastManager.php163-169

Fluent Configuration API

The PendingBroadcast class provides a fluent interface for event configuration:

Method	Parameters	Purpose
via()	?string $connection	Specify the broadcast connection/driver to use
toOthers()	None	Exclude the current user from receiving the broadcast

These methods modify the underlying event object by calling corresponding methods on it if they exist:

• via() calls $event->broadcastVia($connection) if the method exists on the event
• toOthers() calls $event->dontBroadcastToCurrentUser() if the method exists on the event

Implementation Reference:

• Configuration methods: src/PendingBroadcast.php20-42

Sources: src/PendingBroadcast.php20-42

Deferred Dispatch Mechanism

The PendingBroadcast class employs a deferred dispatch pattern using PHP's __destruct() magic method:

Dispatch on Destruction:

When the PendingBroadcast object goes out of scope or is explicitly destroyed, its destructor automatically dispatches the configured event through the event dispatcher. This pattern allows for clean, expressive code:

The destructor implementation is simple and direct: src/PendingBroadcast.php47-50

Sources: src/PendingBroadcast.php1-51 src/BroadcastManager.php163-169

---

Immediate vs. Queued Broadcasting

Broadcasting Decision Logic

The BroadcastManager::queue() method implements the core logic that determines whether an event should be broadcast immediately or queued for asynchronous processing:

Sources: src/BroadcastManager.php174-203

ShouldBroadcastNow Interface

Events implementing the ShouldBroadcastNow interface bypass the queue system entirely and are dispatched synchronously using the bus dispatcher's dispatchNow() method. This ensures immediate processing without queue delays.

The check for immediate broadcasting occurs first: src/BroadcastManager.php176-181

Immediate dispatch behavior:

1. Event is cloned to prevent modification side effects
2. Wrapped in BroadcastEvent
3. Dispatched immediately via Dispatcher::dispatchNow()
4. Method returns early, preventing queue operations

Sources: src/BroadcastManager.php176-181

Queue Configuration Inheritance

For events that will be queued, the system determines the target queue through a priority-based resolution:

Priority	Source	Access Method
1 (Highest)	broadcastQueue() method	Method call
2	$broadcastQueue property	Property access
3	$queue property	Property access
4 (Default)	null	Default queue

This queue name resolution is implemented in src/BroadcastManager.php183-188 using a match expression that checks each possibility in order.

The resolved queue name is then passed to the queue system's pushOn() method: src/BroadcastManager.php200-202

Sources: src/BroadcastManager.php183-202

Queue Property Inheritance

The BroadcastEvent wrapper inherits several queue-related properties from the original event to maintain consistent behavior:

Property inheritance occurs during BroadcastEvent construction: src/BroadcastEvent.php47-55

These inherited properties control queue behavior:

• tries: Maximum number of attempts
• timeout: Maximum execution time in seconds
• backoff: Retry delay after exceptions
• afterCommit: Wait for database transaction commit
• maxExceptions: Maximum unhandled exceptions before failure

Sources: src/BroadcastEvent.php15-55

---

Dispatch Lifecycle

Complete Flow Diagram

The following diagram shows the complete lifecycle from creating a pending broadcast to actual event broadcasting:

Key Classes and Methods:

Component	Location	Role
BroadcastManager::event()	src/BroadcastManager.php163-169	Factory method for creating PendingBroadcast instances
PendingBroadcast::__destruct()	src/PendingBroadcast.php47-50	Triggers event dispatch on object destruction
BroadcastManager::queue()	src/BroadcastManager.php174-203	Decision logic for immediate vs. queued broadcasting
BroadcastEvent::handle()	src/BroadcastEvent.php60-85	Processes the queued broadcast job

Sources: src/BroadcastManager.php163-203 src/PendingBroadcast.php1-51 src/BroadcastEvent.php15-85

---

Usage Patterns

Deferred Broadcast with Configuration

Explicit Scoping

Immediate Dispatch Alternative

For events that need immediate processing, implement ShouldBroadcastNow instead of using PendingBroadcast:

The queue() method detects this interface and dispatches immediately: src/BroadcastManager.php176-181

Sources: src/BroadcastManager.php176-181

---

Implementation Details

PendingBroadcast Class Structure

Constructor: src/PendingBroadcast.php14-18

• Stores the event dispatcher from the container
• Stores the event to be broadcast

Fluent Methods: src/PendingBroadcast.php23-42

• Return $this to enable method chaining
• Conditionally call methods on the event if they exist

Destructor: src/PendingBroadcast.php47-50

• Automatically triggered when object is destroyed
• Dispatches event through the event dispatcher

Sources: src/PendingBroadcast.php1-51

---

Related Components

Component	Purpose	Reference
BroadcastEvent	Queue job wrapper for broadcast events	Standard Broadcast Events
UniqueBroadcastEvent	Prevents duplicate event processing	Unique Events
ShouldBroadcastNow	Interface for immediate broadcasting	Event Contracts
BroadcastManager::queue()	Core queuing logic	BroadcastManager

Sources: src/BroadcastManager.php163-203 src/PendingBroadcast.php1-51 src/BroadcastEvent.php1-136