Core Architecture

Purpose and Scope

This page documents the architectural design of the Hypervel Broadcasting system, covering the factory pattern implementation, driver resolution mechanism, event lifecycle, and Hyperf framework integration.

Related Pages:

• BroadcastManager implementation: see page 2.1
• Broadcaster base class: see page 2.2
• Channel types and authentication: see page 2.3
• Broadcasting drivers: see page 3
• Event broadcasting: see page 4

---

Architectural Patterns

The broadcasting system implements three design patterns: Factory Pattern for driver instantiation, Strategy Pattern for interchangeable broadcasters, and Proxy Pattern for connection pooling.

Factory Pattern Implementation

The BroadcastManager class implements the Factory contract src/Contracts/Factory.php7-13 serving as the central factory for broadcaster instances. It maintains a $drivers cache array src/BroadcastManager.php46 and a $customCreators array src/BroadcastManager.php51 for extensibility via the extend() method src/BroadcastManager.php422-426

Factory Pattern: Driver Resolution Flow

Driver Creation Mapping:

Config Driver	Method	Lines
pusher	createPusherDriver()	src/BroadcastManager.php300-303
ably	createAblyDriver()	src/BroadcastManager.php339-342
redis	createRedisDriver()	src/BroadcastManager.php355-363
log	createLogDriver()	src/BroadcastManager.php368-371
null	createNullDriver()	src/BroadcastManager.php376-379
reverb	createReverbDriver() (alias to pusher)	src/BroadcastManager.php292-295

Sources: src/BroadcastManager.php39-464 src/Contracts/Factory.php1-14

Strategy Pattern for Broadcasters

All broadcasters implement the Broadcaster contract src/Contracts/Broadcaster.php9-25 defining a uniform interface for authentication and message broadcasting.

Broadcaster Contract Methods:

Method Signature	Purpose	Lines
auth(RequestInterface $request): mixed	Authenticate channel access request	src/Contracts/Broadcaster.php14
validAuthenticationResponse(RequestInterface $request, mixed $result): mixed	Format authentication response	src/Contracts/Broadcaster.php19
broadcast(array $channels, string $event, array $payload = []): void	Broadcast event to channels	src/Contracts/Broadcaster.php24

The abstract Broadcaster base class src/Broadcasters/Broadcaster.php23 provides common authentication logic, while concrete implementations (PusherBroadcaster, AblyBroadcaster, RedisBroadcaster, etc.) provide driver-specific broadcasting.

The BroadcastManager uses __call() src/BroadcastManager.php460-463 to proxy method calls to the default driver instance:

This enables calling broadcaster methods directly on the manager: $manager->broadcast($channels, $event, $payload) delegates to $manager->driver()->broadcast($channels, $event, $payload).

Sources: src/Contracts/Broadcaster.php1-26 src/Broadcasters/Broadcaster.php23-304 src/BroadcastManager.php460-463

---

Component Architecture

BroadcastManager as Central Orchestrator

The BroadcastManager class src/BroadcastManager.php39-464 orchestrates all broadcasting operations, managing driver lifecycle, HTTP route registration, event queuing, and providing fluent APIs for programmatic broadcasting.

BroadcastManager Responsibilities

Method Categories:

Category	Key Methods	Lines
Driver Management	driver(), connection(), resolve(), purge(), extend()	src/BroadcastManager.php216-427
Route Registration	routes(), userRoutes(), channelRoutes()	src/BroadcastManager.php74-124
Programmatic API	on(), private(), presence(), event()	src/BroadcastManager.php139-169
Queue Integration	queue(), mustBeUniqueAndCannotAcquireLock()	src/BroadcastManager.php174-211
Helpers	socket(), getDefaultDriver(), setDefaultDriver()	src/BroadcastManager.php129-407

Sources: src/BroadcastManager.php39-464

Driver Resolution and Pooling Mechanism

Driver resolution implements caching and connection pooling optimizations. The resolve() method src/BroadcastManager.php244-259 determines if a driver requires pooling by checking the $poolables array src/BroadcastManager.php61

Driver Resolution Sequence

Poolable Drivers Configuration:

The $poolables array src/BroadcastManager.php61 specifies drivers that use connection pooling:

Pooling wraps the broadcaster in a BroadcastPoolProxy src/BroadcastManager.php56 using the HasPoolProxy trait src/BroadcastManager.php41 enabling connection reuse for external service drivers.

Resolution Flow Steps:

1. driver($name) src/BroadcastManager.php224-229 - Entry point
2. getDefaultDriver() src/BroadcastManager.php396-399 - If name is null
3. Check $drivers[$name] cache src/BroadcastManager.php228
4. get($name) src/BroadcastManager.php234-237 - Retrieve from cache or resolve
5. resolve($name) src/BroadcastManager.php244-259 - Load config and determine pooling
6. getConfig($name) src/BroadcastManager.php384-391 - Fetch driver config
7. createPoolProxy() or doResolve() src/BroadcastManager.php252-258 - Create instance
8. Cache in $drivers[$name] src/BroadcastManager.php228

Sources: src/BroadcastManager.php41-259 src/BroadcastManager.php384-399

Configuration-Based Driver Selection

Driver selection uses the ConfigInterface for hierarchical configuration lookup. The getDefaultDriver() method src/BroadcastManager.php396-399 retrieves the default from broadcasting.default, while getConfig() src/BroadcastManager.php384-391 fetches driver-specific configuration from broadcasting.connections.{name}.

Configuration Keys:

Config Key	Retrieved By	Purpose	Lines
broadcasting.default	getDefaultDriver()	Default driver name	src/BroadcastManager.php398
broadcasting.connections.{name}	getConfig()	Driver-specific config	src/BroadcastManager.php387

The getConfig() method has special handling for the null driver src/BroadcastManager.php386-390:

Sources: src/BroadcastManager.php224-259 src/BroadcastManager.php384-399

---

Event Broadcasting Lifecycle

Synchronous vs Asynchronous Broadcasting

The queue() method src/BroadcastManager.php174-203 determines execution mode based on event interfaces and methods.

Broadcasting Decision Flow

Execution Mode Determination:

Condition	Lines	Result
$event instanceof ShouldBroadcastNow	src/BroadcastManager.php176	Immediate dispatch via Dispatcher::dispatchNow()
method_exists($event, 'shouldBroadcastNow') && $event->shouldBroadcastNow()	src/BroadcastManager.php177	Immediate dispatch via Dispatcher::dispatchNow()
$event instanceof ShouldBeUnique and lock acquired	src/BroadcastManager.php192-198	Queued as UniqueBroadcastEvent
$event instanceof ShouldBeUnique and lock failed	src/BroadcastManager.php195-197	Skipped (duplicate prevention)
Standard ShouldBroadcast	src/BroadcastManager.php200-202	Queued as BroadcastEvent

Sources: src/BroadcastManager.php174-211

Queue Integration Architecture

The queue() method src/BroadcastManager.php174-203 wraps events in job classes and determines queue names using a priority hierarchy.

Queue Name Resolution Priority:

Priority Order:

1. broadcastQueue() method src/BroadcastManager.php184
2. $broadcastQueue property src/BroadcastManager.php185
3. $queue property src/BroadcastManager.php186
4. null (default queue) src/BroadcastManager.php187

Event Wrapping and Lock Mechanisms:

Event Type	Job Wrapper	Lock Mechanism	Dispatch Method
ShouldBroadcastNow	BroadcastEvent	None	Dispatcher::dispatchNow() src/BroadcastManager.php179
ShouldBeUnique (lock acquired)	UniqueBroadcastEvent	UniqueLock::acquire() via uniqueVia()	Queue::pushOn() src/BroadcastManager.php200-202
ShouldBeUnique (lock failed)	None	Lock check prevents queueing	Skipped src/BroadcastManager.php195-197
Standard ShouldBroadcast	BroadcastEvent	None	Queue::pushOn() src/BroadcastManager.php200-202

Unique Event Lock Acquisition:

The mustBeUniqueAndCannotAcquireLock() method src/BroadcastManager.php208-211 uses the UniqueLock class:

The lock uses either a custom cache instance returned by $event->uniqueVia() or the default Cache factory, preventing duplicate event processing through cache-based locking.

Sources: src/BroadcastManager.php174-211

---

Integration Architecture

HTTP Route Registration

The BroadcastManager provides three methods for registering authentication endpoints.

Route Registration Methods

Registered Routes:

Method	Endpoint	HTTP Methods	Controller Action	Lines
routes()	/broadcasting/auth	GET, POST	BroadcastController::authenticate	src/BroadcastManager.php74-95
userRoutes()	/broadcasting/user-auth	GET, POST	BroadcastController::authenticateUser	src/BroadcastManager.php100-114
channelRoutes()	(alias to routes())	GET, POST	BroadcastController::authenticate	src/BroadcastManager.php121-124

Default Middleware Configuration:

The routes() method applies default attributes if none provided src/BroadcastManager.php77-80:

Multi-Kernel Registration:

Routes are registered across all HTTP kernels configured in server.kernels src/BroadcastManager.php83-94:

Sources: src/BroadcastManager.php74-124

Programmatic Broadcasting API

The BroadcastManager provides fluent methods for ad-hoc broadcasting without event classes.

Programmatic Broadcasting Methods

API Methods:

Method	Parameters	Return Type	Purpose	Lines
on()	array|Channel|string $channels	AnonymousEvent	Create anonymous broadcast for public channels	src/BroadcastManager.php139-142
private()	string $channel	AnonymousEvent	Create anonymous broadcast for private channel	src/BroadcastManager.php147-150
presence()	string $channel	AnonymousEvent	Create anonymous broadcast for presence channel	src/BroadcastManager.php155-158
event()	mixed $event = null	PendingBroadcast	Wrap event for deferred broadcast	src/BroadcastManager.php163-169
socket()	?RequestInterface $request = null	?string	Extract socket ID from request header	src/BroadcastManager.php129-134

Usage Patterns:

Sources: src/BroadcastManager.php129-169

Container and Service Integration

The BroadcastManager receives only the ContainerInterface in its constructor src/BroadcastManager.php66-69 and retrieves services lazily on demand.

Lazy Service Resolution

Service Resolution Pattern:

All service dependencies are resolved using $this->app->get(ServiceClass::class) when needed:

Service	Resolution Method	Usage Context	Lines
ConfigInterface	$this->app->get(ConfigInterface::class)	Config access	src/BroadcastManager.php83 src/BroadcastManager.php361 src/BroadcastManager.php387 src/BroadcastManager.php398
RouterDispatcherFactory	$this->app->get(RouterDispatcherFactory::class)	Route registration	src/BroadcastManager.php86 src/BroadcastManager.php107
EventDispatcherInterface	$this->app->get(EventDispatcherInterface::class)	Event dispatch	src/BroadcastManager.php166
Dispatcher (Bus)	$this->app->get(Dispatcher::class)	Job dispatch	src/BroadcastManager.php179
Queue::class (Factory)	$this->app->get(Queue::class)	Queue operations	src/BroadcastManager.php200
RedisFactory	$this->app->get(RedisFactory::class)	Redis driver	src/BroadcastManager.php359
LoggerInterface	$this->app->get(LoggerInterface::class)	Logging	src/BroadcastManager.php330 src/BroadcastManager.php370

This lazy resolution pattern minimizes coupling and allows the manager to function with only required dependencies available.

Sources: src/BroadcastManager.php66-69 src/BroadcastManager.php83-370

---

Summary

The broadcasting architecture implements a factory-based design where BroadcastManager orchestrates driver resolution, route registration, and event dispatching. Drivers implement the Broadcaster contract for interchangeability, with pooling optimization for external services. Events flow through either synchronous or asynchronous paths based on interfaces, with queue integration supporting unique event processing through cache-based locking. The system integrates deeply with Hyperf's HTTP routing, dependency injection, and queue infrastructure to provide a unified broadcasting abstraction.

Sources: src/BroadcastManager.php1-469 src/Contracts/Broadcaster.php1-26 src/Contracts/Factory.php1-14