Broadcast Messages

This document explains the construction of broadcast messages for real-time notification delivery to connected clients via WebSocket channels. Broadcast messages represent arbitrary data payloads that are dispatched as events through the broadcasting system for immediate delivery.

For information about the broadcast channel's delivery mechanism and integration with the broadcasting service, see Broadcast Channel. For details on the overall notification sending flow, see Core Architecture.

---

Purpose and Structure

Broadcast messages enable real-time notifications by wrapping arbitrary data into events that are dispatched to connected clients through WebSocket channels, Pusher, Ably, Redis pub/sub, or other broadcast transports. Unlike email or Slack messages that require specific formatting, broadcast messages consist of simple key-value data arrays.

The BroadcastMessage class serves as a lightweight container that:

• Holds arbitrary notification data as an array
• Supports queue configuration through the Queueable trait
• Integrates seamlessly with the BroadcastChannel for event dispatching

Diagram: BroadcastMessage Class Structure

Sources: src/Messages/BroadcastMessage.php1-32

---

Basic Message Construction

The BroadcastMessage constructor accepts a single data array parameter containing the notification payload. Notifications that support broadcast delivery implement a toBroadcast() method that returns either a BroadcastMessage instance or a plain array.

Component	Type	Description
data	array	Key-value pairs representing the notification payload
connection	string (inherited)	Queue connection for async broadcasting
queue	string (inherited)	Queue name for async broadcasting
delay	int (inherited)	Delay in seconds before broadcasting

Example notification method signature:

The data() method allows fluent modification of the message data after instantiation src/Messages/BroadcastMessage.php26-31:

Sources: src/Messages/BroadcastMessage.php18-31

---

Queue Configuration

Through the Queueable trait src/Messages/BroadcastMessage.php11 broadcast messages inherit methods for configuring asynchronous delivery:

Diagram: Queue Configuration Flow

These queue properties are transferred to the BroadcastNotificationCreated event by the BroadcastChannel src/Channels/BroadcastChannel.php36-39:

This allows the broadcasting system to queue the event delivery rather than dispatching it synchronously.

Sources: src/Messages/BroadcastMessage.php11 src/Channels/BroadcastChannel.php36-39

---

Channel Processing

The BroadcastChannel processes broadcast messages through a defined extraction and event wrapping sequence:

Diagram: BroadcastChannel Processing Sequence

The getData() method src/Channels/BroadcastChannel.php49-60 attempts to extract notification data using this precedence:

1. toBroadcast($notifiable) method - returns BroadcastMessage or array
2. toArray($notifiable) method - returns array
3. Throws RuntimeException if neither method exists

The extracted data (either $message->data or the array itself) is passed to the BroadcastNotificationCreated event constructor src/Channels/BroadcastChannel.php30-34

Sources: src/Channels/BroadcastChannel.php26-42 src/Channels/BroadcastChannel.php49-60

---

Event Structure and Broadcasting

The BroadcastNotificationCreated event implements ShouldBroadcast src/Events/BroadcastNotificationCreated.php16 marking it for real-time delivery through the broadcasting system:

Diagram: BroadcastNotificationCreated Event Structure

Property/Method	Purpose
notifiable	The entity receiving the notification
notification	The notification instance
data	The notification data array
broadcastOn()	Determines which broadcast channels receive the event
broadcastWith()	Customizes the data sent with the broadcast
broadcastType()	Identifies the notification type
broadcastAs()	Customizes the event name

Sources: src/Events/BroadcastNotificationCreated.php16-33

---

Channel Name Resolution

The event's broadcastOn() method src/Events/BroadcastNotificationCreated.php38-59 resolves broadcast channel names through multiple strategies:

Diagram: Broadcast Channel Resolution Strategy

The resolution follows this precedence src/Events/BroadcastNotificationCreated.php40-58:

1. Anonymous Notifiable Routing: If the notifiable is AnonymousNotifiable and has broadcast routing configured
2. Notification Method: If the notification implements broadcastOn() and returns non-empty channels
3. Notifiable Method: If the notifiable implements receivesBroadcastNotificationsOn($notification)
4. Default Generation: Generates channel name as ClassName.Key (e.g., App.User.123)

All resolved channels are wrapped in PrivateChannel instances before being returned.

Sources: src/Events/BroadcastNotificationCreated.php38-73

---

Broadcast Payload Customization

The broadcastWith() method src/Events/BroadcastNotificationCreated.php78-88 determines the data sent to clients:

Diagram: Broadcast Payload Construction

Default payload structure:

Notifications can override this by implementing broadcastWith() to fully control the payload structure.

The broadcastType() method src/Events/BroadcastNotificationCreated.php93-98 returns either:

• The result of notification->broadcastType() if implemented
• The notification's fully qualified class name as fallback

The broadcastAs() method src/Events/BroadcastNotificationCreated.php104-108 determines the event name:

• Returns notification->broadcastAs() if implemented
• Defaults to Hypervel\Notifications\Events\BroadcastNotificationCreated

Sources: src/Events/BroadcastNotificationCreated.php78-108

---

Integration with Broadcasting System

Once the BroadcastNotificationCreated event is dispatched, the Hypervel Broadcasting system handles delivery:

Diagram: Broadcasting System Integration

The broadcasting system:

1. Detects the ShouldBroadcast interface on the event
2. Routes the event to the appropriate broadcast driver(s)
3. Delivers the payload to all clients subscribed to the resolved channels

If the BroadcastMessage specified queue configuration, the event is queued before broadcasting src/Channels/BroadcastChannel.php37-38 enabling asynchronous delivery for high-throughput scenarios.

Sources: src/Channels/BroadcastChannel.php26-42 src/Events/BroadcastNotificationCreated.php16-19

---

Complete Class Reference

BroadcastMessage

Location: src/Messages/BroadcastMessage.php9-32

Properties:

• data (array): The notification data

Methods:

• __construct(array $data): Creates a new message instance
• data(array $data): static: Sets the message data

Traits:

• Hypervel\Bus\Queueable: Provides queue configuration methods

---

BroadcastChannel

Location: src/Channels/BroadcastChannel.php13-61

Constructor Parameters:

• EventDispatcherInterface $events: PSR-14 event dispatcher

Methods:

• send(mixed $notifiable, Notification $notification): mixed: Sends the notification by dispatching an event
• getData(mixed $notifiable, Notification $notification): mixed: Extracts data from notification using toBroadcast() or toArray()

---

BroadcastNotificationCreated

Location: src/Events/BroadcastNotificationCreated.php16-109

Properties:

• notifiable (mixed): The notifiable entity
• notification (Notification): The notification instance
• data (array): The notification data

Methods:

• broadcastOn(): array: Returns the broadcast channels
• broadcastWith(): array: Returns the broadcast payload
• broadcastType(): string: Returns the notification type identifier
• broadcastAs(): string: Returns the event name
• channelName(): array|string: Generates the default channel name

Interfaces:

• Hypervel\Broadcasting\Contracts\ShouldBroadcast: Marks for broadcasting

Traits:

• Hypervel\Bus\Queueable: Provides queue configuration
• Hypervel\Queue\SerializesModels: Enables model serialization

Sources: src/Messages/BroadcastMessage.php1-32 src/Channels/BroadcastChannel.php1-61 src/Events/BroadcastNotificationCreated.php1-109