Job Chaining

Purpose and Scope

This document explains how to execute jobs sequentially using job chains in hypervel/bus. Job chaining allows you to define a series of jobs that execute one after another, where each job dispatches the next job in the chain upon successful completion.

For information about configuring individual jobs before dispatch, see Configuring Job Dispatch. For information about executing multiple jobs concurrently with progress tracking, see Batch Processing.

---

Overview

Job chaining is a mechanism for orchestrating sequential workflows where jobs must execute in a specific order. When a job in a chain completes successfully, it automatically dispatches the next job in the chain. If any job in the chain fails, the remaining jobs are not executed unless error handling is configured.

The system consists of three primary components:

Component	Purpose	File
PendingChain	Builder class for creating and configuring chains	src/PendingChain.php
Queueable trait	Provides chain management methods and properties	src/Queueable.php
ChainedBatch	Enables batches to be included in chains	src/ChainedBatch.php

Sources: src/PendingChain.php1-156 src/Queueable.php1-280 src/ChainedBatch.php1-131

---

Creating a Chain

Using the Queueable Trait

Jobs that use the Queueable trait can create chains using the static withChain() method. This method is typically provided by the Dispatchable trait which works in conjunction with Queueable.

The first job executes immediately (or is queued), and upon successful completion, it dispatches the second job, which then dispatches the third job, and so on.

Sources: src/Queueable.php48-50 src/Queueable.php166-175

Chain Properties in Queueable

The Queueable trait defines several properties for managing chains:

Property	Type	Purpose
$chained	array	Serialized jobs to be executed after this job
$chainConnection	?string	Connection for subsequent chain jobs
$chainQueue	?string	Queue for subsequent chain jobs
$chainCatchCallbacks	?array	Error callbacks for chain failures

Sources: src/Queueable.php48-65

---

Chain Configuration with PendingChain

The PendingChain class provides a fluent interface for configuring chains before dispatch.

Chain Configuration Diagram

Sources: src/PendingChain.php20-156

Configuration Methods

Connection and Queue

The onConnection() and onQueue() methods specify where chain jobs should be dispatched:

These settings apply to all jobs in the chain unless individual jobs override them.

Sources: src/PendingChain.php59-74

Delay

The delay() method sets an initial delay before the first job in the chain executes:

Sources: src/PendingChain.php79-84

Error Handling

The catch() method registers callbacks to execute if any job in the chain fails:

Multiple catch callbacks can be registered by calling catch() multiple times.

Sources: src/PendingChain.php89-96

PendingChain Properties

Property	Type	Default	Purpose
$connection	?string	null	Connection for chain jobs
$queue	?string	null	Queue for chain jobs
$delay	DateInterval|DateTimeInterface|int|null	null	Initial delay
$catchCallbacks	array	[]	Failure callbacks
$job	mixed	-	First job in the chain
$chain	array	-	Remaining jobs

Sources: src/PendingChain.php27-52

---

Chain Dispatch and Execution Flow

Dispatch Process

When PendingChain::dispatch() is called, the following sequence occurs:

1. The first job is instantiated (if provided as a class name)
2. Chain configuration is applied to the first job
3. Subsequent jobs are serialized and attached to the first job
4. The first job is dispatched through the Dispatcher

Sources: src/PendingChain.php109-139

Job Instantiation

The dispatch() method handles three types of first jobs:

Type	Handling
String (class name)	Instantiated with new $this->job(...func_get_args())
Closure	Wrapped in CallQueuedClosure::create()
Object	Used directly

Sources: src/PendingChain.php111-117

Applying Configuration to First Job

Configuration from PendingChain is merged with the first job's existing configuration:

Sources: src/PendingChain.php119-131

---

Chain Execution Within Jobs

The Queueable Trait's Chain Methods

The Queueable trait provides methods for managing chains during job execution:

chain()

Sets the array of jobs to execute after the current job:

This method:

1. Prepares nested batches using ChainedBatch::prepareNestedBatches()
2. Serializes each job
3. Stores serialized jobs in the $chained property

Sources: src/Queueable.php166-175

dispatchNextJobInChain()

Called when a job completes successfully to dispatch the next job:

This method:

1. Checks if $chained is not empty
2. Unserializes the next job from the array
3. Transfers chain configuration to the next job
4. Dispatches the next job

Sources: src/Queueable.php224-238

Chain Execution Flow Diagram

Sources: src/Queueable.php224-248

Chain Configuration Propagation

When dispatching the next job in a chain, the following configuration is transferred:

Each job preserves its own connection/queue settings if specified, otherwise inherits from the chain.

Sources: src/Queueable.php227-236

---

Advanced Chain Configuration

Setting Connection and Queue for All Jobs

The Queueable trait provides methods to set connection and queue for both the current job and all subsequent chain jobs:

allOnConnection()

Sets both $this->connection and $this->chainConnection to ensure all jobs use the same connection.

Sources: src/Queueable.php90-98

allOnQueue()

Sets both $this->queue and $this->chainQueue to ensure all jobs use the same queue.

Sources: src/Queueable.php103-111

Modifying Chains Dynamically

Jobs can modify their own chain during execution:

prependToChain()

Adds a job at the beginning of the remaining chain (executes next):

Sources: src/Queueable.php180-187

appendToChain()

Adds a job at the end of the remaining chain:

Sources: src/Queueable.php192-199

Chain Modification Example

---

Error Handling in Chains

Catch Callbacks

When a job in a chain fails, the invokeChainCatchCallbacks() method is invoked:

All registered catch callbacks receive the exception that caused the failure.

Sources: src/Queueable.php243-248

Catch Callback Registration

Callbacks are registered via PendingChain::catch() and stored in serialized form:

Closures are wrapped in SerializableClosure to enable queue serialization.

Sources: src/PendingChain.php89-96

---

Nested Batches in Chains

ChainedBatch Class

The ChainedBatch class allows PendingBatch instances to be included in job chains. When a PendingBatch is added to a chain, it is automatically converted to a ChainedBatch.

Sources: src/ChainedBatch.php1-131

ChainedBatch Structure

Property	Type	Purpose
$jobs	Collection	Jobs in the batch
$name	string	Batch name
$options	array	Batch configuration

The class implements ShouldQueue and uses the Batchable, Dispatchable, InteractsWithQueue, and Queueable traits.

Sources: src/ChainedBatch.php14-34

Batch Preparation in Chains

The prepareNestedBatches() static method recursively processes job collections to convert PendingBatch instances:

This method is called by both Queueable::chain() and the ChainedBatch constructor.

Sources: src/ChainedBatch.php50-58 src/Queueable.php168

ChainedBatch Execution

When a ChainedBatch executes, it:

1. Converts itself back to a PendingBatch via toPendingBatch()
2. Attaches remaining chain jobs to the batch's finally callback
3. Dispatches the batch

Sources: src/ChainedBatch.php63-68 src/ChainedBatch.php104-130

Conversion to PendingBatch

The toPendingBatch() method recreates a PendingBatch with the stored configuration:

Chain catch callbacks are converted to batch catch callbacks, executing only if the batch does not allow failures.

Sources: src/ChainedBatch.php73-99

Attaching Chain Continuation

The attachRemainderOfChainToEndOfBatch() method ensures subsequent chain jobs execute after the batch completes:

The next chain job is dispatched in the batch's finally callback, ensuring it runs whether the batch succeeds or fails (unless cancelled).

Sources: src/ChainedBatch.php104-130

---

Conditional Dispatch

PendingChain provides methods for conditional dispatching:

dispatchIf()

Dispatches the chain only if a condition is true:

Sources: src/PendingChain.php144-147

dispatchUnless()

Dispatches the chain only if a condition is false:

Sources: src/PendingChain.php152-155

---

Testing Support

The Queueable trait includes assertion methods for testing chains:

assertHasChain()

Verifies that a job has the expected chain attached:

The method can compare either class names or serialized job instances.

Sources: src/Queueable.php253-270

assertDoesntHaveChain()

Verifies that a job has no remaining chained jobs:

Sources: src/Queueable.php275-278

---

Job Serialization

serializeJob()

Chain jobs are serialized before storage in the $chained array:

Closures are converted to CallQueuedClosure instances before serialization, enabling queued closures if the hypervel/queue package is installed.

Sources: src/Queueable.php206-219

---

Complete Chain Flow Diagram

Sources: src/PendingChain.php1-156 src/Queueable.php166-248