Overview

This document provides a high-level introduction to the Hypervel Broadcasting package, a real-time event broadcasting system for the Hyperf framework. It covers the package's purpose, architecture, core components, and capabilities.

For installation and configuration details, see Installation & Configuration. For basic usage examples, see Basic Usage. For detailed architecture information, see Core Architecture.

Sources: composer.json1-60 README.md1-5

Purpose and Scope

The Hypervel Broadcasting package enables real-time event broadcasting in Hyperf applications. It provides a unified interface for sending events to various broadcasting backends including Pusher, Ably, Redis pub/sub, and others. The package supports multiple channel types (public, private, presence), queue-based asynchronous broadcasting, connection pooling for external services, and HTTP-based channel authentication.

The package implements a driver-based architecture where the BroadcastManager acts as a factory and router, delegating actual broadcast operations to driver-specific implementations. Events can be broadcast immediately or queued for asynchronous processing.

Sources: src/BroadcastManager.php36-39 composer.json1-12

Package Structure

Diagram: Package Component Structure

This diagram shows the physical organization of the package and how major components relate to each other. The BroadcastManager at src/BroadcastManager.php39-464 serves as the central factory, creating and managing driver instances. The abstract Broadcaster class defines the interface that all driver implementations extend. The event system provides wrappers for different broadcasting scenarios.

Sources: src/BroadcastManager.php1-464 composer.json23-27

Core Components

BroadcastManager

The BroadcastManager class at src/BroadcastManager.php39-464 implements the Factory contract and serves as the central orchestration point. It provides:

• Driver Resolution: Creates and caches broadcaster driver instances via the driver() and connection() methods at src/BroadcastManager.php216-229
• Event Queuing: Handles event queuing logic via the queue() method at src/BroadcastManager.php174-203
• Route Registration: Registers HTTP authentication routes via the routes() method at src/BroadcastManager.php74-95
• Fluent API: Provides convenience methods like on(), private(), presence(), and event() at src/BroadcastManager.php139-169
• Driver Extensibility: Supports custom driver registration via the extend() method at src/BroadcastManager.php422-427

For detailed documentation, see BroadcastManager.

Sources: src/BroadcastManager.php39-464

Broadcaster Implementations

Five concrete broadcaster implementations are provided:

Driver	Class	Purpose	Configuration Key
Pusher	PusherBroadcaster	Pusher and Reverb services	pusher, reverb
Ably	AblyBroadcaster	Ably service	ably
Redis	RedisBroadcaster	Redis pub/sub	redis
Log	LogBroadcaster	Debugging/testing	log
Null	NullBroadcaster	Disabled broadcasting	null

The Pusher and Ably drivers support connection pooling via BroadcastPoolProxy at src/BroadcastManager.php56-61 The Redis driver uses Lua scripts for efficient multi-channel broadcasting. For driver details, see Broadcasting Drivers.

Sources: src/BroadcastManager.php292-379 src/BroadcastManager.php61

Event System

The package provides several event-related classes:

• BroadcastEvent: Wraps events implementing ShouldBroadcast for queue processing at src/BroadcastManager.php190
• UniqueBroadcastEvent: Extends BroadcastEvent with unique lock support for events implementing ShouldBeUnique at src/BroadcastManager.php193
• AnonymousEvent: Enables ad-hoc broadcasts without formal event classes, created via BroadcastManager::on() at src/BroadcastManager.php139-142
• PendingBroadcast: Provides fluent configuration interface, created via BroadcastManager::event() at src/BroadcastManager.php163-169

For event system details, see Event Broadcasting.

Sources: src/BroadcastManager.php139-203

Channel Types

Four channel types are supported, each with distinct naming conventions and authentication requirements:

• Channel: Base public channel, no authentication required
• PrivateChannel: Private channels prefixed with private-, requires authentication
• PresenceChannel: Presence channels prefixed with presence-, requires authentication and returns user data
• EncryptedPrivateChannel: Encrypted private channels prefixed with private-encrypted-

Channel authentication is handled via the /broadcasting/auth endpoint registered by BroadcastManager::routes(). For channel details, see Channel Types & Authentication.

Sources: src/BroadcastManager.php74-95

Broadcasting Flow

Diagram: Event Broadcasting Lifecycle

This sequence diagram illustrates the complete flow from application code to external service. The BroadcastManager at src/BroadcastManager.php174-203 determines whether to broadcast immediately or queue the event based on interfaces implemented by the event. For queued events, the BroadcastEvent wrapper is created and pushed to the queue system. Unique events acquire locks via src/BroadcastManager.php208-211 to prevent duplicate processing.

Sources: src/BroadcastManager.php174-211

Configuration and Initialization

Diagram: Configuration and Initialization Flow

The package integrates with Hyperf via the ConfigProvider specified in composer.json52-54 The BroadcastManager resolves drivers lazily via methods like createPusherDriver(), createAblyDriver(), etc. at src/BroadcastManager.php292-379 Drivers listed in the $poolables array at src/BroadcastManager.php61 are wrapped in connection pools via src/BroadcastManager.php252-258

Sources: composer.json52-54 src/BroadcastManager.php244-279 src/BroadcastManager.php61

Authentication System

Channel authentication for private and presence channels occurs via HTTP requests to the /broadcasting/auth endpoint registered by src/BroadcastManager.php74-95 The BroadcastController handles authentication requests and delegates to the Broadcaster::auth() method.

The authentication flow involves:

1. Client sends POST request to /broadcasting/auth with channel_name parameter
2. BroadcastController retrieves the authenticated user
3. Broadcaster::auth() invokes registered channel authenticator callbacks
4. Callbacks receive implicitly bound parameters (e.g., route model binding)
5. Access is granted (returns user data) or denied (throws exception)

For authentication details, see Authentication & Authorization. For channel details, see Channel Types & Authentication.

Sources: src/BroadcastManager.php74-95

Driver Architecture

Diagram: Broadcaster Class Hierarchy

The BroadcastManager at src/BroadcastManager.php39-464 implements a factory pattern with driver creation methods at src/BroadcastManager.php292-379 Each driver extends the abstract Broadcaster class which defines the common interface. The BroadcastPoolProxy wraps Ably and Pusher drivers to provide connection pooling as specified in src/BroadcastManager.php61

Sources: src/BroadcastManager.php39-464 src/BroadcastManager.php292-379

Contracts and Interfaces

The package defines several contracts that establish its API surface:

Contract	Location	Purpose
Factory	src/Contracts/Factory.php	Broadcasting manager interface
Broadcaster	src/Contracts/Broadcaster.php	Driver implementation interface
ShouldBroadcast	src/Contracts/ShouldBroadcast.php	Marks events as broadcastable
ShouldBroadcastNow	src/Contracts/ShouldBroadcastNow.php	Immediate broadcast marker
ShouldBeUnique	src/Contracts/ShouldBeUnique.php	Unique event marker
HasBroadcastChannel	src/Contracts/HasBroadcastChannel.php	Entity-channel association

The BroadcastManager implements the Factory contract at src/BroadcastManager.php39 Events implement ShouldBroadcast to enable broadcasting. For contract details, see Contracts & Interfaces.

Sources: src/BroadcastManager.php20-22 src/Contracts/HasBroadcastChannel.php1-19

Dependencies and Requirements

The package requires PHP 8.2+ and integrates with several Hyperf and Hypervel packages:

Core Dependencies:

• hyperf/contract: Hyperf framework contracts
• hyperf/http-server: HTTP server for authentication routes
• hyperf/pool: Connection pooling infrastructure
• hypervel/auth: User authentication
• hypervel/bus: Event/command bus and job dispatching
• hypervel/cache: Unique lock implementation
• hypervel/queue: Asynchronous broadcasting
• hypervel/object-pool: Connection pool proxy pattern

Optional Dependencies:

• ably/ably-php: Ably driver (^1.0)
• pusher/pusher-php-server: Pusher driver (^6.0|^7.0)
• hyperf/redis: Redis driver (~3.1.0)
• ext-hash: Signature generation for Ably/Pusher

Sources: composer.json28-47

Extension Points

The package provides several extension mechanisms:

1. Custom Drivers: Register custom broadcasters via BroadcastManager::extend() at src/BroadcastManager.php422-427
2. Channel Authenticators: Register channel authorization callbacks via Broadcaster methods
3. Pool Configuration: Configure connection pooling via the pool configuration key
4. Queue Customization: Control queue connection and name via event properties

For custom driver implementation, see Custom Broadcasters.

Sources: src/BroadcastManager.php422-427