Queue Manager

The QueueManager class (src/QueueManager.php) is the central orchestrator for queue operations in the Hypervel Queue system. It implements both the FactoryContract and MonitorContract interfaces, serving as the primary factory for creating queue connections and providing monitoring capabilities. The QueueManager manages queue driver connectors, handles connection caching, implements connection pooling for expensive resources, and integrates with the event system for job lifecycle hooks.

This document provides comprehensive documentation of the QueueManager class, its responsibilities, connection resolution logic, driver registration system, and extension points. For details on specific queue drivers, see page 4. For worker process management, see page 5.

---

Core Responsibilities

The QueueManager class implements the following responsibilities:

• Connection Factory: Creates and caches queue connection instances based on configuration, implementing the FactoryContract interface
• Driver Registration: Registers and resolves queue driver connectors for nine supported backends (null, sync, database, redis, beanstalkd, sqs, defer, coroutine, failover)
• Connection Pooling: Wraps Beanstalkd and SQS drivers with QueuePoolProxy for connection pooling and resource efficiency
• Event Integration: Provides convenience methods (before(), after(), failing(), etc.) to register event listeners for job lifecycle events
• Configuration Management: Retrieves queue connection configuration from ConfigInterface and manages default connection selection
• Dynamic Delegation: Proxies method calls to the default queue connection via __call() magic method
• Extension Points: Allows custom drivers to be registered via extend() and addConnector() methods

Sources: src/QueueManager.php29-32 src/QueueManager.php62-69

System Architecture: QueueManager in Context

Diagram: QueueManager and Related Code Entities

This diagram shows how the QueueManager class serves as the central hub for queue management. It implements FactoryContract and MonitorContract, maintains cached connections and connector registrations, and coordinates connection pooling for expensive drivers.

Sources: src/QueueManager.php29-55 src/QueueManager.php277-389

Connection Resolution Flow

Diagram: "QueueManager::connection()" Resolution Logic

This flow illustrates how QueueManager::connection() resolves and caches queue connection instances, including configuration validation and pool proxy creation for specific drivers.

Sources: src/QueueManager.php135-178

Driver Registration and Extension

The QueueManager registers nine built-in queue drivers during initialization via the registerConnectors() method. Each driver is associated with a connector class that implements ConnectorInterface. Drivers in the poolables array are wrapped with a QueuePoolProxy for connection pooling.

Driver	Connector Class	Pool Proxy	Use Case
null	NullConnector	No	Testing/no-op operations
sync	SyncConnector	No	Immediate synchronous execution
database	DatabaseConnector	No	Database table storage
redis	RedisConnector	No	Redis lists/sorted sets
beanstalkd	BeanstalkdConnector	Yes	Beanstalkd tube system
sqs	SqsConnector	Yes	Amazon SQS queues
defer	DeferConnector	No	Coroutine defer execution
coroutine	CoroutineConnector	No	Async coroutine execution
failover	FailoverConnector	No	Failover queue configuration

Diagram: registerConnectors() and Connector Registration Flow

The registration system uses closures to lazy-load connector instances. Each register*Connector() method calls addConnector() with a closure that returns the connector instance. This supports dependency injection from the container and enables custom driver extension via extend() or addConnector().

Sources: src/QueueManager.php277-389

Connection Pooling Management

The QueueManager implements connection pooling for drivers with expensive connection overhead. Drivers listed in the poolables property (['beanstalkd', 'sqs']) are wrapped with a QueuePoolProxy instance to manage a pool of reusable connections. This reduces connection establishment overhead and improves performance for high-throughput scenarios.

Diagram: Pool Proxy Decision Logic in resolve() Method

The poolables array contains ['beanstalkd', 'sqs'] because these drivers establish network connections that benefit from pooling. Other drivers (redis, database) leverage existing connection managers from their respective services. The pool configuration is retrieved from $config['pool'] if present.

Sources: src/QueueManager.php52-59 src/QueueManager.php156-180

Event System Integration

The QueueManager provides methods to register event listeners for key job lifecycle events. These methods internally use the application's event dispatcher to listen for specific event classes.

Method	Event Class	Purpose
before()	JobProcessing	Before job execution
after()	JobProcessed	After successful job execution
exceptionOccurred()	JobExceptionOccurred	When job throws an exception
looping()	Looping	On each worker daemon loop iteration
failing()	JobFailed	When a job permanently fails
stopping()	WorkerStopping	When the worker is shutting down

Example Usage:

Sources: src/QueueManager.php72-123

Dynamic Method Delegation

The QueueManager implements the __call() magic method to delegate method calls to the default queue connection. This allows application code to call queue methods directly on the QueueManager instance without explicitly resolving a connection.

Diagram: Dynamic Delegation to Default Connection via __call()

This pattern enables seamless access to queue operations. Methods like push(), pop(), later(), and bulk() can be called directly on the QueueManager, and they are automatically delegated to the default connection. The @mixin annotation on the class docblock provides IDE autocompletion for these delegated methods.

Sources: src/QueueManager.php29-30 src/QueueManager.php272-276

Configuration Management

The QueueManager retrieves configuration through the ConfigInterface:

• Default Driver: queue.default configuration key
• Connection Config: queue.connections.{name} for specific connections
• Null Handling: Returns ['driver' => 'null'] for null/undefined connections

Method	Purpose	Configuration Key
getDefaultDriver()	Get default connection name	queue.default
getConfig()	Get connection configuration	queue.connections.{name}
setDefaultDriver()	Change default connection	Updates queue.default

Sources: src/QueueManager.php212-236