Contracts & Interfaces

The broadcasting system defines its public API through six core contracts located in src/Contracts/. These interfaces establish behavioral contracts for broadcaster implementations, event broadcasting, channel authentication, and model integration.

For broadcaster implementations, see Broadcasting Drivers. For event usage patterns, see Event Broadcasting.

Core Broadcasting Contracts

The broadcasting system defines two fundamental contracts that establish the primary API for broadcast operations and broadcaster management.

Factory Contract

The Factory interface defines the contract for accessing broadcaster instances. It provides the primary entry point for obtaining configured broadcast drivers.

Factory Contract Definition

The Factory contract requires a single method:

• connection(?string $name): Broadcaster - Returns a broadcaster instance for the specified connection name, or the default connection if null

The BroadcastManager implements this contract, managing driver instances via internal caching and factory methods.

Sources: src/Contracts/Factory.php1-13

Broadcaster Contract

The Broadcaster interface defines the core operations that all broadcasting drivers must implement: channel authentication and event broadcasting.

Broadcaster Contract Definition

The contract defines three methods:

• auth(RequestInterface $request): mixed - Authenticates channel subscription requests
• validAuthenticationResponse(RequestInterface $request, mixed $result): mixed - Formats authentication responses for the client
• broadcast(array $channels, string $event, array $payload = []): void - Publishes events to specified channels

All concrete broadcasters extend the abstract Broadcaster base class which provides shared authentication logic.

Sources: src/Contracts/Broadcaster.php1-25

Event Broadcasting Contracts

Event broadcasting contracts define the behavioral requirements for events that participate in the broadcasting system. These contracts determine when, where, and how events should be broadcast.

ShouldBroadcast Contract

The ShouldBroadcast interface marks events as eligible for broadcasting and defines their target channels.

ShouldBroadcast Contract Definition

The contract requires a single method:

• broadcastOn(): Channel|Channel[]|string[] - Returns channels for broadcasting as Channel object(s) or channel name strings

Events implementing this interface are wrapped in BroadcastEvent jobs and queued for asynchronous broadcasting.

Sources: src/Contracts/ShouldBroadcast.php1-17

ShouldBroadcastNow Contract

The ShouldBroadcastNow interface marks events for immediate synchronous broadcasting, bypassing the queue system.

ShouldBroadcastNow Contract Definition

This interface extends ShouldBroadcast without adding methods. Events implementing this interface are broadcast immediately when dispatched instead of being queued via BroadcastEvent jobs. The event dispatcher checks for this interface to determine synchronous vs asynchronous broadcasting.

Sources: src/Contracts/ShouldBroadcastNow.php1-9

ShouldBeUnique Contract

The ShouldBeUnique interface marks events for deduplication via cache-based locking to prevent duplicate broadcasts.

ShouldBeUnique Contract Definition

This marker interface has no methods. Events implementing this interface are wrapped in UniqueBroadcastEvent instead of BroadcastEvent. The wrapper acquires a cache lock before broadcasting to prevent duplicate processing. Lock keys are generated via the event's uniqueId() method, and lock duration is controlled via uniqueFor().

Sources: src/Contracts/ShouldBeUnique.php1-9

Channel-Related Contracts

HasBroadcastChannel Contract

The HasBroadcastChannel interface enables models to define their broadcast channel names, supporting implicit model binding in channel authorization callbacks.

HasBroadcastChannel Contract Definition

The contract defines two methods:

• broadcastChannelRoute(): string - Returns the channel route template containing parameter placeholders (e.g., "user.{id}")
• broadcastChannel(): string - Returns the fully resolved channel name with actual values (e.g., "user.123")

The abstract Broadcaster class uses these methods during channel authentication to resolve model instances from channel parameters via implicit binding.

Sources: src/Contracts/HasBroadcastChannel.php1-18

Contract Implementation Overview

The following diagram shows the complete relationship between all contracts and their primary implementing classes within the broadcasting system:

Complete Contract Implementation Map

This implementation hierarchy ensures consistent behavior across all broadcasting drivers while allowing for driver-specific optimizations and features. The contract system provides strong typing and clear behavioral expectations for all components within the broadcasting system.

Sources: src/Contracts/Factory.php1-13 src/Contracts/Broadcaster.php1-25 src/Contracts/ShouldBroadcast.php1-17 src/Contracts/HasBroadcastChannel.php1-18