 |
VOOZH | about |
|
VOOZH | about |
This document covers the AblyBroadcaster implementation, which integrates the Ably real-time messaging service as a broadcasting driver. The AblyBroadcaster handles authentication, signature generation, channel formatting, and message publishing for Ably channels.
For information about the abstract Broadcaster base class and shared authentication mechanisms, see Broadcaster Base Class. For configuration details, see Installation & Configuration. For connection pooling optimizations, see Object Pooling & Performance.
Sources: src/Broadcasters/AblyBroadcaster.php1-203
The AblyBroadcaster class extends the abstract Broadcaster class and implements the Ably-specific logic for real-time event broadcasting. It uses the Ably REST SDK (AblyRest) to publish messages to Ably channels and manages authentication for private and presence channels.
| Responsibility | Implementation |
|---|---|
| Channel Authentication | Validates subscription requests and generates HMAC signatures |
| Channel Formatting | Converts Laravel-style channel names to Ably's colon-separated format |
| Message Publishing | Publishes events to Ably channels via REST API |
| Token Management | Extracts public and private tokens from Ably API key |
| User Data Handling | Includes user information in presence channel authentication |
Sources: src/Broadcasters/AblyBroadcaster.php18-27
Sources: src/Broadcasters/AblyBroadcaster.php18-203
The authentication process for Ably channels follows a two-step pattern: validation and signature generation. The auth() method validates the request, while validAuthenticationResponse() generates the appropriate authentication response.
Sources: src/Broadcasters/AblyBroadcaster.php34-86
The AblyBroadcaster implements channel name handling to bridge Laravel/Hyperf naming conventions with Ably's channel format.
The isGuardedChannel() method identifies channels that require authentication:
Sources: src/Broadcasters/AblyBroadcaster.php135-138
The normalizeChannelName() method strips prefixes for internal processing:
| Input Channel | Normalized Output | Purpose |
|---|---|---|
private-chat.1 | chat.1 | Used for user authentication callbacks |
presence-lobby | lobby | Used for user authentication callbacks |
notifications | notifications | Public channels pass through unchanged |
Sources: src/Broadcasters/AblyBroadcaster.php143-152
The formatChannels() method converts normalized channel names to Ably's colon-separated format:
Examples:
private-chat.1 → private:chat.1presence-lobby → presence:lobbynotifications → public:notificationsSources: src/Broadcasters/AblyBroadcaster.php158-170
Ably API keys follow the format publicToken:privateToken. The broadcaster extracts these components:
| Method | Purpose | Implementation |
|---|---|---|
getPublicToken() | Extracts public portion | Returns string before : delimiter |
getPrivateToken() | Extracts private portion | Returns string after : delimiter |
Sources: src/Broadcasters/AblyBroadcaster.php175-186
The generateAblySignature() method creates HMAC-SHA256 signatures for channel authentication:
Signature Components:
hash_hmac('sha256', "{socketId}:{channelName}", privateToken)hash_hmac('sha256', "{socketId}:{channelName}:{json(userData)}", privateToken)Sources: src/Broadcasters/AblyBroadcaster.php91-98
The validAuthenticationResponse() method generates different response structures based on channel type:
For channels starting with private-:
For channels starting with presence-:
The presence channel user data includes:
| Field | Source | Purpose |
|---|---|---|
user_id | getAuthIdentifierForBroadcasting() or getAuthIdentifier() | Unique user identifier |
user_info | Result from channel authenticator callback | Additional user metadata |
Sources: src/Broadcasters/AblyBroadcaster.php54-86
Sources: src/Broadcasters/AblyBroadcaster.php105-118
The buildAblyMessage() method creates an AblyMessage object with the following properties:
| Property | Value | Purpose |
|---|---|---|
name | Event name (e.g., OrderShipped) | Identifies the event type |
data | Full payload array | Contains event data |
connectionKey | Value from payload['socket'] | Excludes originating socket from receiving broadcast |
Sources: src/Broadcasters/AblyBroadcaster.php123-130
The broadcaster wraps Ably SDK exceptions in BroadcastException:
Exception Hierarchy:
AblyException (from Ably SDK)BroadcastException (application-level exception)Sources: src/Broadcasters/AblyBroadcaster.php113-117 src/BroadcastException.php1-11
The Ably broadcaster is configured in config/autoload/broadcasting.php:
| Variable | Format | Example |
|---|---|---|
ABLY_KEY | publicToken:privateToken | abc123:xyz789def |
Sources: Referenced from context about configuration patterns
auth(RequestInterface $request): mixedAuthenticates channel subscription requests.
Parameters:
$request: HTTP request containing channel_name and socket_idReturns: Result from channel authenticator callback
Throws: AccessDeniedHttpException if authentication fails
Sources: src/Broadcasters/AblyBroadcaster.php34-49
validAuthenticationResponse(RequestInterface $request, mixed $result): mixedGenerates the authentication response for successful channel authorization.
Parameters:
$request: HTTP request containing channel_name and socket_id$result: Result from channel authenticator callbackReturns: Array with auth key and optionally channel_data for presence channels
Sources: src/Broadcasters/AblyBroadcaster.php54-86
generateAblySignature(string $channelName, string $socketId, ?array $userData = null): stringGenerates HMAC-SHA256 signature for channel authentication.
Parameters:
$channelName: Full channel name (e.g., private-chat.1)$socketId: Client socket identifier$userData: Optional user data array for presence channelsReturns: HMAC signature string
Sources: src/Broadcasters/AblyBroadcaster.php91-98
broadcast(array $channels, string $event, array $payload = []): voidPublishes an event to specified channels.
Parameters:
$channels: Array of channel names$event: Event name$payload: Event payload dataThrows: BroadcastException if publishing fails
Sources: src/Broadcasters/AblyBroadcaster.php105-118
isGuardedChannel(string $channel): boolDetermines if a channel requires authentication.
Parameters:
$channel: Channel nameReturns: true if channel starts with private- or presence-, false otherwise
Sources: src/Broadcasters/AblyBroadcaster.php135-138
normalizeChannelName(string $channel): stringRemoves authentication prefixes from channel names.
Parameters:
$channel: Original channel nameReturns: Normalized channel name without prefix
Sources: src/Broadcasters/AblyBroadcaster.php143-152
getAbly(): AblyRestRetrieves the underlying Ably SDK instance.
Returns: AblyRest instance
Sources: src/Broadcasters/AblyBroadcaster.php191-194
setAbly(AblyRest $ably): voidSets the underlying Ably SDK instance.
Parameters:
$ably: New AblyRest instanceSources: src/Broadcasters/AblyBroadcaster.php199-202
buildAblyMessage(string $event, array $payload = []): AblyMessageConstructs an Ably message object for broadcasting.
Parameters:
$event: Event name$payload: Event payloadReturns: Configured AblyMessage instance
Sources: src/Broadcasters/AblyBroadcaster.php123-130
formatChannels(array $channels): arrayConverts Laravel-style channel names to Ably's colon-separated format.
Parameters:
$channels: Array of channel namesReturns: Array of formatted channel names
Sources: src/Broadcasters/AblyBroadcaster.php158-170
getPublicToken(): stringExtracts the public token from the Ably API key.
Returns: Public token string
Sources: src/Broadcasters/AblyBroadcaster.php175-178
getPrivateToken(): stringExtracts the private token from the Ably API key.
Returns: Private token string
Sources: src/Broadcasters/AblyBroadcaster.php183-186
| Dependency | Purpose | Location |
|---|---|---|
ContainerInterface | Dependency injection container | Constructor parameter |
AblyRest | Ably SDK REST client | Constructor parameter |
RequestInterface | HTTP request abstraction | Method parameters |
Sources: src/Broadcasters/AblyBroadcaster.php23-27
The AblyBroadcaster leverages methods from the abstract Broadcaster class:
| Method | Purpose |
|---|---|
verifyUserCanAccessChannel() | Executes channel authenticator callbacks with parameter binding |
retrieveUser() | Retrieves authenticated user from request using configured guard |
For details on these methods, see Broadcaster Base Class.
Sources: src/Broadcasters/AblyBroadcaster.php45-48
When configured with the pool option, the AblyBroadcaster can be wrapped in a BroadcastPoolProxy for connection pooling. This optimization reuses Ably REST client connections across multiple broadcast operations.
For detailed information on connection pooling configuration and behavior, see Object Pooling & Performance.
Sources: Referenced from system architecture context
Refresh this wiki