Configuring Job Dispatch

Purpose and Scope

This document explains how to configure jobs after they are wrapped in a PendingDispatch or PendingClosureDispatch object but before they are dispatched to the queue or executed synchronously. The configuration API provides a fluent interface for setting queue connections, delays, transaction timing, chains, and other dispatch parameters.

For information about creating job objects and using the Queueable trait, see Queueable Trait. For details about static dispatch methods on job classes, see Dispatchable Trait. For batch-specific configuration, see Creating and Managing Batches. For chain-specific features, see Job Chaining.

---

The PendingDispatch Wrapper

The PendingDispatch class acts as a configuration wrapper around job objects. When you call dispatch($job) or use static dispatch methods, the job is wrapped in a PendingDispatch instance that provides a fluent API for configuration before the job is actually dispatched.

Figure 1: PendingDispatch Wrapper Flow

The PendingDispatch object holds a reference to the underlying job and delegates configuration calls to it. When the PendingDispatch object goes out of scope, its destructor automatically dispatches the job to the appropriate destination.

Sources: src/PendingDispatch.php15-28

---

Configuration Methods

Connection and Queue Configuration

The PendingDispatch class provides methods to configure which queue connection and queue name the job should use:

Method	Parameters	Purpose
onConnection()	BackedEnum|string|null	Sets the queue connection for the job
onQueue()	BackedEnum|string|null	Sets the queue name for the job
allOnConnection()	BackedEnum|string|null	Sets the connection for the entire job chain
allOnQueue()	BackedEnum|string|null	Sets the queue for the entire job chain

All methods delegate to the underlying job object and return the PendingDispatch instance for method chaining.

Figure 2: Connection and Queue Configuration Delegation

The allOnConnection() and allOnQueue() methods src/PendingDispatch.php53-68 are specifically designed for jobs with chains, applying the configuration to all jobs in the chain rather than just the first job.

Sources: src/PendingDispatch.php33-68

Delay Configuration

Jobs can be configured to execute after a specified delay:

Method	Parameters	Purpose
delay()	DateInterval|DateTimeInterface|int|null	Sets the delay before job execution
withoutDelay()	None	Removes any configured delay

The delay() method src/PendingDispatch.php73-78 accepts three types of delay specifications:

• Integer: Delay in seconds
• DateTimeInterface: Specific time to execute the job
• DateInterval: Relative time interval

The withoutDelay() method src/PendingDispatch.php83-88 resets the delay to zero, useful for conditional delay logic.

Sources: src/PendingDispatch.php73-88

Transaction Timing Configuration

These methods control when the job is dispatched relative to database transactions:

Method	Purpose
afterCommit()	Job dispatch waits until all database transactions have committed
beforeCommit()	Job is dispatched immediately without waiting for transactions

The afterCommit() method src/PendingDispatch.php93-98 ensures that jobs are not dispatched if the current database transaction is rolled back, preventing jobs from processing data that was never persisted. The beforeCommit() method src/PendingDispatch.php103-108 explicitly disables this behavior.

Sources: src/PendingDispatch.php93-108

Chain Management

The chain() method src/PendingDispatch.php113-118 configures jobs that should execute after the current job completes successfully:

Figure 3: Chain Configuration

This method delegates to the underlying job's chain() method, which is typically provided by the Queueable trait. For detailed information about job chaining, see Job Chaining.

Sources: src/PendingDispatch.php113-118

Response Timing Configuration

The afterResponse() method src/PendingDispatch.php123-128 configures the job to be dispatched after the HTTP response has been sent to the browser:

Figure 4: afterResponse Flag Usage

Unlike other configuration methods that delegate to the job, this method sets a flag on the PendingDispatch instance itself src/PendingDispatch.php20 which is checked during dispatch in the destructor.

Sources: src/PendingDispatch.php20 src/PendingDispatch.php123-128

---

The Dispatch Mechanism

The PendingDispatch class uses PHP's destructor mechanism to automatically dispatch jobs when the object goes out of scope. This creates a convenient API where configuration and dispatch happen in a single expression.

Figure 5: Destructor-Based Dispatch Sequence

The destructor src/PendingDispatch.php159-173 follows this logic:

1. Uniqueness Check: Calls shouldDispatch() to determine if the job should be dispatched
2. Response Timing: Checks the $afterResponse flag to determine which dispatch method to use
3. Dispatcher Resolution: Retrieves the Dispatcher from the DI container
4. Job Dispatch: Calls either dispatch() or dispatchAfterResponse() on the dispatcher

Sources: src/PendingDispatch.php159-173

---

Unique Job Handling

The shouldDispatch() method src/PendingDispatch.php133-144 implements the uniqueness constraint checking:

Figure 6: Unique Job Dispatch Check

The method checks if the job implements the ShouldBeUnique interface src/PendingDispatch.php135 If it does, an UniqueLock is created using the cache factory, and the lock acquisition is attempted. If the lock cannot be acquired (meaning another instance of the job is already running), the job is not dispatched.

For more details about unique jobs, see Unique Jobs.

Sources: src/PendingDispatch.php133-144

---

PendingClosureDispatch Extension

The PendingClosureDispatch class extends PendingDispatch to provide additional configuration specific to closure-based jobs:

Figure 7: PendingClosureDispatch Inheritance

The catch() method src/PendingClosureDispatch.php14-19 adds a failure callback to closure-based jobs:

Method	Parameters	Purpose
catch()	Closure $callback	Registers a callback to execute if the closure job fails

This method delegates to the underlying job's onFailure() method, which is specific to CallQueuedClosure jobs. Regular job classes use the Queueable trait's failure handling mechanisms instead.

Sources: src/PendingClosureDispatch.php9-20

---

Dynamic Method Proxying

The PendingDispatch class implements a magic __call() method src/PendingDispatch.php149-154 that proxies any unrecognized method calls to the underlying job object:

Figure 8: Dynamic Method Proxying

This enables the PendingDispatch to support custom methods defined on job classes without explicitly implementing them. The proxy always returns the PendingDispatch instance itself ($this), maintaining the fluent interface even for custom methods.

This is particularly useful for jobs that implement custom configuration methods beyond those provided by the Queueable trait.

Sources: src/PendingDispatch.php149-154

---

Configuration Method Summary

Category	Methods	Delegation Target
Connection	onConnection(), allOnConnection()	Job's connection property
Queue	onQueue(), allOnQueue()	Job's queue property
Delay	delay(), withoutDelay()	Job's delay property
Transactions	afterCommit(), beforeCommit()	Job's transaction flags
Chaining	chain()	Job's chain array
Response Timing	afterResponse()	PendingDispatch's $afterResponse flag
Failure Handling	catch() (closures only)	Job's failure callbacks
Custom	Any other method	Job via __call() proxy

Sources: src/PendingDispatch.php33-154 src/PendingClosureDispatch.php14-19