Broadcasting Contracts

Purpose and Scope

This document details the core broadcasting contracts that define the fundamental interface for the broadcasting system. These contracts establish the API surface that enables driver interchangeability, allowing different broadcaster implementations to be used seamlessly without changing application code. The two primary contracts are Factory and Broadcaster, which together form the foundation of the system's extensibility.

For event-related interfaces such as ShouldBroadcast and ShouldBeUnique, see Event Contracts. For concrete implementations of these contracts, see Broadcasting Drivers.

---

Contract Architecture Overview

The broadcasting system uses a two-tier contract architecture that separates driver resolution from broadcasting operations. This design enables both compile-time type safety and runtime flexibility.

Sources: src/Contracts/Factory.php1-13 src/Contracts/Broadcaster.php1-25

---

Factory Contract

The Factory interface defines the entry point for obtaining broadcaster instances. It provides a single method that resolves driver implementations by name.

Interface Definition

Method	Parameters	Return Type	Purpose
connection	?string $name = null	Broadcaster	Retrieves a broadcaster implementation by connection name

The connection method accepts an optional connection name that corresponds to keys defined in the broadcasting.php configuration file. When null is passed, the default connection is returned.

Implementation Requirements

Classes implementing Factory must:

1. Resolve connection names to broadcaster configurations
2. Cache resolved instances to avoid redundant instantiation
3. Support default connections when no name is provided
4. Throw exceptions for invalid or missing connection names

The BroadcastManager class serves as the primary implementation of this contract. See BroadcastManager for implementation details.

Sources: src/Contracts/Factory.php1-13

---

Broadcaster Contract

The Broadcaster interface defines the core operations that all broadcasting drivers must implement. It encompasses three primary responsibilities: authentication, authentication response formatting, and event broadcasting.

Interface Methods

Method	Parameters	Return Type	Purpose
auth	RequestInterface $request	mixed	Authenticates incoming channel subscription requests
validAuthenticationResponse	RequestInterface $request mixed $result	mixed	Formats successful authentication responses for the specific driver
broadcast	array $channels string $event array $payload = []	void	Publishes events to specified channels

Authentication Methods

The authentication methods work together to secure private and presence channels:

auth(RequestInterface $request)

src/Contracts/Broadcaster.php14

This method performs the actual authentication logic. It:

• Extracts the channel name from the HTTP request
• Determines if the authenticated user has access to the channel
• Invokes registered channel authenticator callbacks
• Returns authorization data (varies by driver)

The return type is mixed because different drivers require different authentication data structures. For example:

• Pusher: Returns an array with auth and optionally channel_data keys
• Ably: Returns token strings and capability objects
• Redis: May return boolean values or simple authorization flags

validAuthenticationResponse(RequestInterface $request, mixed $result)

src/Contracts/Broadcaster.php19

This method transforms the raw authentication result from auth() into a properly formatted HTTP response compatible with the client-side driver. Different broadcasting services expect different response formats:

Driver	Response Format
Pusher	JSON object with auth signature and optional channel_data
Ably	JSON object with token or signed request
Redis	Simple boolean or JSON acknowledgment

Sources: src/Contracts/Broadcaster.php11-20

Broadcasting Method

broadcast(array $channels, string $event, array $payload = [])

src/Contracts/Broadcaster.php24

This is the core method that publishes events to channels. The method signature provides flexibility while maintaining consistency:

Parameters:

• $channels: Array of channel names (strings) where the event should be published. Supports:

  • Public channels: my-channel
  • Private channels: private-my-channel
  • Presence channels: presence-my-channel
  • Encrypted channels: private-encrypted-my-channel

• $event: Event name as a string. This is typically the fully-qualified class name of the event being broadcast, but can be any string identifier.

• $payload: Associative array containing the event data to be transmitted. Must be JSON-serializable.

The method returns void because broadcasting is typically fire-and-forget. Errors are handled through exceptions rather than return values.

Sources: src/Contracts/Broadcaster.php22-24

---

Contract Interaction Pattern

The contracts work together to provide a complete broadcasting workflow. The following diagram illustrates how application code interacts with both contracts:

Workflow Steps

1. Driver Resolution: The application requests a broadcaster through Factory::connection(), receiving a Broadcaster instance
2. Broadcasting: The application invokes Broadcaster::broadcast() to publish events
3. Authentication: When clients subscribe, the application uses Broadcaster::auth() and Broadcaster::validAuthenticationResponse() to authorize access

Sources: src/Contracts/Factory.php1-13 src/Contracts/Broadcaster.php1-25

---

Driver Interchangeability

The contract-based design enables complete driver interchangeability without code changes. This provides several benefits:

Type Safety

Both contracts use type declarations that enable static analysis:

Factory::connection(?string $name = null): Broadcaster

This guarantees that any connection resolution returns an object implementing Broadcaster, ensuring type-safe method calls throughout the application.

Configuration-Driven Selection

Driver selection happens entirely through configuration:

Configuration Key	Determines
broadcasting.default	Which connection name to use when none specified
broadcasting.connections.*	Available driver instances and their configurations

Changing from Pusher to Ably requires only a configuration change, not code modifications.

Testing and Development

The contracts enable test doubles and development utilities:

• LogBroadcaster: Implements Broadcaster to log events instead of transmitting them
• NullBroadcaster: Implements Broadcaster as a no-op for testing
• Mock implementations: Test suites can provide mock objects satisfying the contracts

Custom Driver Registration

The Factory contract supports custom driver registration through extension mechanisms. Custom broadcasters need only implement the Broadcaster interface to integrate seamlessly:

For details on creating custom broadcasters, see Custom Broadcasters.

Sources: src/Contracts/Factory.php1-13 src/Contracts/Broadcaster.php1-25

---

Contract Method Resolution

The following table maps contract methods to their typical implementation locations:

Contract Method	Primary Implementation	Alternative Implementations
Factory::connection()	BroadcastManager::driver()	None (single implementation)
Broadcaster::auth()	Broadcaster::auth() (abstract base)	Overridden in PusherBroadcaster, AblyBroadcaster
Broadcaster::validAuthenticationResponse()	Broadcaster::validAuthenticationResponse() (abstract base)	Overridden in all concrete broadcasters
Broadcaster::broadcast()	Abstract (must implement)	PusherBroadcaster, AblyBroadcaster, RedisBroadcaster, LogBroadcaster, NullBroadcaster

The abstract Broadcaster class provides default implementations for auth() that can be used by most drivers, while validAuthenticationResponse() and broadcast() require driver-specific logic. See Broadcaster Base Class for the abstract implementation details.

Sources: src/Contracts/Broadcaster.php1-25

---

Summary

The broadcasting contracts provide a minimal yet complete interface for the entire broadcasting system:

• Factory: Single-method contract for obtaining broadcaster instances
• Broadcaster: Three-method contract defining authentication and broadcasting operations

This contract-driven architecture enables:

• Type-safe driver resolution
• Complete driver interchangeability through configuration
• Extensibility through custom implementations
• Simplified testing with mock objects

All broadcaster implementations must satisfy the Broadcaster contract, while the BroadcastManager serves as the sole implementation of the Factory contract, acting as the central orchestration point for the entire system.

Sources: src/Contracts/Factory.php1-13 src/Contracts/Broadcaster.php1-25