Standard Broadcast Events

Purpose and Scope

This page describes the standard approach to broadcasting events in Hypervel Broadcasting. Standard broadcast events are regular event classes that implement the ShouldBroadcast interface, which are automatically wrapped in a BroadcastEvent job for queued processing. This page covers the creation of broadcastable events, the wrapping mechanism, the complete event processing lifecycle, and how queue configuration properties are inherited from the event to the job wrapper.

For immediate (non-queued) broadcasts, see Immediate vs Queued Broadcasting. For preventing duplicate event processing, see Unique Events. For ad-hoc broadcasts without formal event classes, see Anonymous Events.

---

ShouldBroadcast Interface

Events that should be broadcast must implement the ShouldBroadcast interface. This marker interface signals to the broadcasting system that the event should be queued for broadcasting. The interface requires implementing the broadcastOn() method, which returns one or more channels to broadcast on.

Sources: Referenced from high-level architecture diagrams

---

Event Method Contracts

A broadcastable event class can implement several methods to control broadcast behavior:

Method	Required	Return Type	Purpose
broadcastOn()	Yes	`Channel	Channel[]`
broadcastAs()	No	string	Customizes the event name (defaults to class name)
broadcastWith()	No	array	Specifies the payload data (defaults to public properties)
broadcastConnections()	No	array	Specifies which connections to use (defaults to [null])

Sources: src/BroadcastEvent.php68-84

---

The BroadcastEvent Wrapper

The BroadcastEvent class serves as a queued job wrapper around event instances. When an event implementing ShouldBroadcast is dispatched, the BroadcastManager wraps it in a BroadcastEvent instance and pushes it to the queue system.

The BroadcastEvent wrapper implements ShouldQueue, making it a queued job that can be processed by the queue worker system. It uses the Queueable trait to provide standard queue job functionality.

Sources: src/BroadcastEvent.php15-17

---

Queue Configuration Inheritance

When creating a BroadcastEvent wrapper, queue configuration properties are automatically inherited from the wrapped event instance. This allows event classes to define queue behavior that will be respected during broadcast processing.

The following properties are inherited during wrapper construction:

Property	Type	Purpose
tries	int|null	Number of times the job may be attempted
timeout	int|null	Number of seconds before the job times out
backoff	int|null	Seconds to wait before retrying on exception
afterCommit	bool|null	Whether to wait for database commit before queueing
maxExceptions	int|null	Maximum unhandled exceptions before failing

Sources: src/BroadcastEvent.php47-55

---

Event Processing Lifecycle

When a BroadcastEvent job is processed by the queue worker, the handle() method orchestrates the complete broadcasting operation.

The lifecycle steps are:

1. Channel Extraction: Calls broadcastOn() on the event and wraps result in an array
2. Empty Check: Returns early if no channels specified
3. Event Name Resolution: Uses broadcastAs() if available, otherwise uses the event's class name
4. Connection Resolution: Uses broadcastConnections() if available, otherwise defaults to [null] (default connection)
5. Payload Extraction: Calls getPayloadFromEvent() to build the broadcast payload
6. Broadcasting Loop: For each connection, retrieves the broadcaster and calls broadcast() with channels, name, and payload

Sources: src/BroadcastEvent.php60-85

---

Payload Extraction Mechanism

The getPayloadFromEvent() method determines what data will be broadcast for an event. It follows a specific priority order for payload extraction.

Payload Extraction Priority

1. Custom Payload (Highest Priority): If the event defines broadcastWith() and it returns a non-null value, that payload is used with the socket field merged in
2. Automatic Reflection (Fallback): If no broadcastWith() method exists or it returns null, all public properties are extracted using reflection

Property Formatting

The formatProperty() method handles special value types:

• If the value implements Arrayable, calls toArray() on it
• Otherwise, returns the value unchanged

The broadcastQueue property is explicitly removed from the payload to prevent queue configuration from being broadcast.

Sources: src/BroadcastEvent.php90-119

---

Broadcasting to Multiple Connections

Events can broadcast to multiple broadcasting connections simultaneously by implementing the broadcastConnections() method. This enables scenarios like broadcasting the same event to both Pusher and Redis, or to different Pusher instances.

If broadcastConnections() is not defined, the event broadcasts using the default connection (represented by null in the connections array).

Sources: src/BroadcastEvent.php72-84

---

Job Display Name

The BroadcastEvent implements the displayName() method to provide a human-readable name for the queued job in logs and monitoring tools. It returns the class name of the wrapped event, making it easy to identify which event is being broadcast in queue dashboards.

Sources: src/BroadcastEvent.php124-127

---

Cloning Behavior

The BroadcastEvent implements the __clone() magic method to ensure deep cloning of the wrapped event instance. When the wrapper is cloned, the event itself is also cloned, preventing shared references between job instances in the queue system.

Sources: src/BroadcastEvent.php132-135

---

Relationship to ShouldBroadcastNow

While standard broadcast events are queued for asynchronous processing, events implementing the ShouldBroadcastNow interface are broadcast immediately without queuing. The ShouldBroadcastNow interface extends ShouldBroadcast, indicating it has all the same requirements but different processing behavior.

Events implementing only ShouldBroadcast (not ShouldBroadcastNow) are wrapped in BroadcastEvent for queued processing. Events implementing ShouldBroadcastNow bypass the wrapper and are broadcast synchronously.

Sources: src/Contracts/ShouldBroadcastNow.php7-8

---

Summary Table: BroadcastEvent Behavior

Aspect	Implementation	Default Behavior
Event Name	broadcastAs() method	Fully-qualified class name
Payload	broadcastWith() method	All public properties via reflection
Channels	broadcastOn() method (required)	No default; must be implemented
Connections	broadcastConnections() method	[null] (default connection)
Queue Config	Event properties: tries, timeout, etc.	Inherited from event if present
Socket Exclusion	Event socket property	Included in payload if present
Job Name	Event class name	Used for queue monitoring

Sources: src/BroadcastEvent.php1-137