Queue Operations

The Queue system provides an interface for asynchronous job processing across multiple queue backends. This page documents the Queue facade and its underlying QueueManager and Queue implementations for pushing jobs, managing connections, inspecting queue state, and extending with custom drivers.

For event dispatching and listeners, see Event System. For testing queue operations with QueueFake, see Queue Testing. For Redis-specific operations that may underlie queue storage, see Redis Operations.

Queue System Architecture

The Queue system follows the Manager pattern to support multiple queue drivers and connections. Jobs are pushed to queues for asynchronous processing by workers.

Sources: src/Facades/Queue.php1-114

Facade Accessor and Core Methods

The Queue facade resolves to Hypervel\Queue\Contracts\Factory, which is typically implemented by QueueManager. The facade provides static access to all queue operations.

Method Category	Key Methods	Description
Job Pushing	push(), pushOn(), pushRaw()	Dispatch jobs to queues
Delayed Jobs	later(), laterOn()	Schedule jobs for future execution
Bulk Operations	bulk()	Push multiple jobs at once
Job Retrieval	pop()	Retrieve next job from queue
Queue Inspection	size(), pendingSize(), delayedSize()	Monitor queue state
Connections	connection(), connected()	Manage queue connections
Configuration	getDefaultDriver(), setDefaultDriver()	Configure driver selection
Extension	extend(), addConnector()	Register custom drivers
Testing	fake(), assertPushed()	Test doubles and assertions

Sources: src/Facades/Queue.php14-72

Connection Management

The Queue system supports multiple named queue connections, each potentially using different drivers (Redis, Database, SQS, etc.).

Accessing Queue Connections

Connection Methods

Method	Return Type	Description
Queue::connection(?string $name)	Queue\Contracts\Queue	Get a specific queue connection
Queue::connected(?string $name)	bool	Check if connection exists
Queue::getDefaultDriver()	string	Get the default driver name
Queue::setDefaultDriver(string $name)	void	Set the default driver
Queue::getName(?string $connection)	string	Get the queue name for a connection

Sources: src/Facades/Queue.php21-27

Default vs Named Connections

When no connection name is specified, methods use the default driver configured in the queue manager. Named connections allow routing different job types to different backends:

Sources: src/Facades/Queue.php22-26

Pushing Jobs to Queues

The Queue facade provides multiple methods for dispatching jobs to queues with varying levels of control.

Push Operations Overview

Sources: src/Facades/Queue.php41-46

Push Method Signatures

Method	Parameters	Description
push(object|string $job, mixed $data = '', ?string $queue = null)	Job instance or class name, optional data, optional queue name	Push job to queue immediately
pushOn(?string $queue, object|string $job, mixed $data = '')	Queue name, job, optional data	Push to specific queue (queue-first signature)
pushRaw(string $payload, ?string $queue = null, array $options = [])	Pre-serialized payload, optional queue, options	Push raw payload without serialization
bulk(array $jobs, mixed $data = '', ?string $queue = null)	Array of jobs, optional data, optional queue	Push multiple jobs at once

Usage Examples:

Sources: src/Facades/Queue.php41-46

Delayed Job Execution

Jobs can be scheduled for execution after a specified delay using later() and laterOn() methods.

Delay Specification

Delays can be specified as:

• Integer: Seconds from now
• DateTimeInterface: Specific timestamp
• DateInterval: Time interval from now

Sources: src/Facades/Queue.php44-45

Delayed Job Methods

Method	Parameters	Description
later(DateInterval|DateTimeInterface|int $delay, object|string $job, mixed $data = '', ?string $queue = null)	Delay, job, optional data, optional queue	Schedule job for later execution
laterOn(?string $queue, DateInterval|DateTimeInterface|int $delay, object|string $job, mixed $data = '')	Queue name, delay, job, optional data	Schedule job on specific queue

Usage Examples:

Sources: src/Facades/Queue.php44-45

Queue Inspection

The Queue facade provides methods for monitoring queue state and job counts across different states.

Queue State Methods

Method	Return Type	Description
size(?string $queue = null)	int	Total number of jobs in queue
pendingSize(?string $queue = null)	int	Number of pending (ready) jobs
delayedSize(?string $queue = null)	int	Number of delayed jobs
reservedSize(?string $queue = null)	int	Number of reserved (processing) jobs
creationTimeOfOldestPendingJob(?string $queue = null)	?int	Unix timestamp of oldest pending job

Queue State Diagram:

Usage Examples:

Sources: src/Facades/Queue.php36-40

Job Retrieval and Processing

Workers retrieve jobs from queues using the pop() method. The popUsing() method allows customizing job retrieval behavior.

Job Retrieval Flow

Sources: src/Facades/Queue.php47-86

Pop Methods

Method	Parameters	Return Type	Description
pop(?string $queue = null)	Optional queue name	Queue\Contracts\Job|null	Retrieve next job from queue
Queue::popUsing(string $workerName, callable $callback)	Worker name, callback	void	Register custom job retrieval callback

Worker Registration:

The popUsing() static method delegates to Worker::popUsing() to register custom callbacks for job retrieval:

Sources: src/Facades/Queue.php47-86

Job Lifecycle Hooks

The Queue system provides callbacks that fire at various points in the job lifecycle, allowing for logging, monitoring, and custom behavior.

Lifecycle Callback Methods

Method	Trigger Point	Callback Parameters
before(mixed $callback)	Before job processing begins	Job instance
after(mixed $callback)	After job completes successfully	Job instance
exceptionOccurred(mixed $callback)	When job throws exception	Job instance, exception
looping(mixed $callback)	Before each queue poll iteration	None
failing(mixed $callback)	When job is failing	Job instance, exception
stopping(mixed $callback)	When worker is stopping	None

Lifecycle Event Flow:

Usage Example:

Sources: src/Facades/Queue.php15-20

Job Configuration Methods

The Queue system provides methods for retrieving job-specific configuration such as retry attempts, backoff delays, and expiration times.

Method	Parameters	Return Type	Description
getJobTries(mixed $job)	Job instance	mixed	Get max retry attempts for job
getJobBackoff(mixed $job)	Job instance	mixed	Get backoff delay between retries
getJobExpiration(mixed $job)	Job instance	mixed	Get job expiration time
createPayloadUsing(?callable $callback)	Callback	void	Customize payload creation

Sources: src/Facades/Queue.php50-53

Driver Extension System

The Queue system uses the Manager pattern to support custom queue drivers through the extend() and addConnector() methods.

Driver Registration Flow

Sources: src/Facades/Queue.php23-24

Extension Methods

Method	Parameters	Description
extend(string $driver, Closure $resolver)	Driver name, resolver closure	Register custom driver resolver
addConnector(string $driver, Closure $resolver)	Driver name, connector closure	Add custom connection factory

Custom Driver Example:

Sources: src/Facades/Queue.php23-24

Connection Pooling

The Queue manager supports connection pooling for drivers that benefit from connection reuse, particularly for Redis-based queues.

Poolable Driver Management

Method	Parameters	Description
addPoolable(string $driver)	Driver name	Mark driver as supporting pooling
removePoolable(string $driver)	Driver name	Remove driver from poolable list
getPoolables()	None	Get list of poolable drivers
setPoolables(array $poolables)	Array of driver names	Set poolable drivers list

Connection Pool Lifecycle:

Sources: src/Facades/Queue.php32-35

Release Callbacks

Release callbacks control how connections are returned to the pool after use:

Method	Parameters	Description
setReleaseCallback(string $driver, Closure $callback)	Driver name, callback	Set connection release behavior
getReleaseCallback(string $driver)	Driver name	Get release callback for driver

Sources: src/Facades/Queue.php30-31

Container and Configuration

The Queue system integrates with the PSR-11 container for dependency injection and configuration management.

Configuration Methods

Method	Return Type	Description
getContainer()	ContainerInterface	Get the service container
setContainer(ContainerInterface $container)	Queue	Set the service container
getConfig()	array	Get queue configuration
setConfig(array $config)	Queue	Set queue configuration
getApplication()	ContainerInterface	Get application container
setApplication(ContainerInterface $app)	QueueManager	Set application container
getConnectionName()	string	Get current connection name
setConnectionName(string $name)	Queue	Set connection name

Container Integration:

Sources: src/Facades/Queue.php28-112

Testing with Queue Fake

The Queue facade provides a fake() method for testing. See Queue Testing for comprehensive documentation on testing queue operations.

Quick Testing Reference

Method	Purpose
Queue::fake()	Replace queue with fake for testing
Queue::assertPushed()	Assert job was pushed
Queue::assertPushedOn()	Assert job pushed to specific queue
Queue::assertNotPushed()	Assert job was not pushed
Queue::assertNothingPushed()	Assert no jobs were pushed

Basic Testing Example:

For detailed testing documentation including assertPushedWithChain(), assertClosurePushed(), except(), and other advanced testing features, see Queue Testing.

Sources: src/Facades/Queue.php58-104

Queue Method Reference Table

Complete Method Overview

Category	Methods
Job Dispatching	push(), pushOn(), pushRaw(), later(), laterOn(), bulk()
Job Retrieval	pop(), popUsing()
Queue Inspection	size(), pendingSize(), delayedSize(), reservedSize(), creationTimeOfOldestPendingJob()
Connections	connection(), connected(), getConnectionName(), setConnectionName()
Driver Management	extend(), addConnector(), getDefaultDriver(), setDefaultDriver(), getName()
Pooling	addPoolable(), removePoolable(), getPoolables(), setPoolables(), setReleaseCallback(), getReleaseCallback()
Configuration	getConfig(), setConfig(), getContainer(), setContainer(), getApplication(), setApplication()
Job Configuration	getJobTries(), getJobBackoff(), getJobExpiration(), createPayloadUsing()
Lifecycle Hooks	before(), after(), exceptionOccurred(), looping(), failing(), stopping()
Testing	fake(), except(), assertPushed(), assertPushedOn(), assertPushedWithChain(), assertPushedWithoutChain(), assertClosurePushed(), assertClosureNotPushed(), assertNotPushed(), assertCount(), assertNothingPushed(), pushed(), hasPushed(), shouldFakeJob(), pushedJobs(), serializeAndRestore()

Sources: src/Facades/Queue.php14-72