Queueable Trait

Purpose and Scope

The Queueable trait provides queue configuration and job chaining capabilities to jobs and commands. It allows jobs to specify their target queue, connection, delay, and middleware, and enables sequential job execution through chains. This trait is typically used in conjunction with the Dispatchable trait (see 5.1) to create fully-featured job classes.

For information about dispatching jobs that use this trait, see 4.1 and 4.2. For information about job chains specifically, see 6.

---

Overview

The Queueable trait is located at src/Queueable.php20 and provides two primary categories of functionality:

1. Queue Configuration: Methods to control where, when, and how a job is dispatched to the queue system
2. Chain Management: Properties and methods to manage sequential job execution, where one job dispatches the next upon successful completion

Jobs that use this trait gain the ability to fluently configure their queue behavior and participate in job chains without implementing complex logic themselves.

Sources: src/Queueable.php1-279

---

Properties

The trait defines several public properties that control job behavior:

Property	Type	Purpose
$connection	?string	The name of the connection the job should be sent to
$queue	?string	The name of the queue the job should be sent to
$delay	array|DateInterval|DateTimeInterface|int|null	The delay before the job becomes available
$afterCommit	?bool	Whether to dispatch after database transactions commit
$middleware	array	Middleware the job should be dispatched through
$chained	array	Serialized jobs that should run if this job succeeds
$chainConnection	?string	The connection for the entire chain
$chainQueue	?string	The queue for the entire chain
$chainCatchCallbacks	?array	Callbacks to execute on chain failure

These properties are set through the trait's configuration methods and read by the dispatcher and queue system during job execution.

Sources: src/Queueable.php22-65

---

Queue Configuration Methods

Connection and Queue Selection

The trait provides methods to specify which connection and queue a job should use:

onConnection()

src/Queueable.php70-75 - Sets the connection for the current job only. Accepts a string, BackedEnum, or null.

onQueue()

src/Queueable.php80-85 - Sets the queue for the current job only. Accepts a string, BackedEnum, or null.

allOnConnection()

src/Queueable.php90-98 - Sets the connection for both the current job and all jobs in the chain. Updates both $connection and $chainConnection.

allOnQueue()

src/Queueable.php103-111 - Sets the queue for both the current job and all jobs in the chain. Updates both $queue and $chainQueue.

Sources: src/Queueable.php68-111

---

Delay Configuration

delay()

src/Queueable.php116-121 - Sets the number of seconds (or other time representation) before the job should become available for processing. Accepts:

• int: seconds
• DateInterval: relative time
• DateTimeInterface: absolute time
• array: per-connection delays
• null: no delay

withoutDelay()

src/Queueable.php126-131 - Explicitly sets the delay to zero seconds, ensuring the job is available immediately.

Sources: src/Queueable.php113-131

---

Transaction Control

afterCommit()

src/Queueable.php136-141 - Indicates that the job should only be dispatched after all database transactions have committed. Sets $afterCommit to true.

beforeCommit()

src/Queueable.php146-151 - Indicates that the job should be dispatched immediately without waiting for database transactions to commit. Sets $afterCommit to false.

These methods control when jobs are pushed to the queue relative to database transaction boundaries, preventing jobs from executing before their associated data is persisted.

Sources: src/Queueable.php133-151

---

Middleware Configuration

through()

src/Queueable.php156-161 - Specifies middleware that the job should be dispatched through. Accepts an array of middleware or a single middleware object, which is wrapped in an array using Arr::wrap().

Middleware can intercept job execution to add logging, error handling, or other cross-cutting concerns.

Sources: src/Queueable.php153-161

---

Chain Management

The Queueable trait provides the core implementation for job chaining, where jobs execute sequentially with each job dispatching the next upon successful completion.

Chain Configuration

chain()

src/Queueable.php166-175 - Sets the array of jobs that should run if the current job succeeds. The method:

1. Calls ChainedBatch::prepareNestedBatches() to handle nested batches within the chain
2. Serializes each job using serializeJob()
3. Stores the serialized jobs in the $chained array

prependToChain()

src/Queueable.php180-187 - Adds a job to the beginning of the chain, so it runs immediately after the current job. Useful for dynamically modifying chains during execution.

appendToChain()

src/Queueable.php192-199 - Adds a job to the end of the chain. The new job will run after all currently chained jobs complete.

Sources: src/Queueable.php163-199

---

Job Serialization

serializeJob()

src/Queueable.php206-219 - Protected method that serializes a job for storage in the chain. Special handling for closures:

• If the job is a Closure, it attempts to wrap it in CallQueuedClosure from the hypervel/queue package
• If hypervel/queue is not installed, throws a RuntimeException
• Otherwise, uses standard PHP serialize()

The serialization allows jobs to be stored in the $chained array and later unserialized for execution.

Sources: src/Queueable.php201-219

---

Chain Execution

Dispatching the Next Job

dispatchNextJobInChain()

src/Queueable.php224-238 - Dispatches the next job in the chain after the current job completes successfully. The method:

1. Checks if $chained is not empty
2. Removes and unserializes the first job from the array using array_shift()
3. Transfers chain state to the next job:
   • Remaining chained jobs
   • Connection and queue (using the job's own settings or falling back to chain settings)
   • Chain-wide connection and queue settings
   • Chain catch callbacks
4. Dispatches the next job using the global dispatch() function

This method is typically called by the queue worker after a job completes successfully.

Sources: src/Queueable.php221-238

---

Chain Failure Handling

invokeChainCatchCallbacks()

src/Queueable.php243-248 - Invokes all catch callbacks registered for the chain when a job in the chain fails. The method:

1. Wraps $chainCatchCallbacks in a Collection
2. Iterates over each callback
3. Calls each callback with the exception as an argument

This allows chains to handle failures gracefully, performing cleanup or logging when any job in the chain fails.

Sources: src/Queueable.php240-248

---

Testing Support

The trait includes assertion methods for testing job chains:

assertHasChain()

src/Queueable.php254-270 - Asserts that the job has a specific chain of jobs attached. The method:

1. Verifies the expected chain is not empty
2. If expected chain contains objects, serializes them for comparison
3. Otherwise, extracts class names from the serialized chain
4. Compares the expected chain with the actual chain using PHPUnit assertions

assertDoesntHaveChain()

src/Queueable.php275-278 - Asserts that the job has no remaining chained jobs. Verifies that $chained is empty.

These methods integrate with PHPUnit and enable testing of chain configuration without dispatching jobs.

Sources: src/Queueable.php250-278

---

Usage Patterns

Basic Queue Configuration

Chain-wide Configuration

Transaction-aware Dispatch

Dynamic Chain Modification

Jobs can modify their own chains during execution:

Sources: src/Queueable.php1-279

---

Property Inheritance in Chains

When a job dispatches the next job in the chain, property values are transferred according to this priority:

1. Job-specific settings ($queue, $connection) - If the next job has its own settings, they are used
2. Chain-wide settings ($chainQueue, $chainConnection) - If the job has no specific settings, chain settings are used
3. Callbacks and remaining chain - Always transferred to maintain chain integrity

Sources: src/Queueable.php224-238