Batch Callbacks and Lifecycle

This document explains the batch callback system in hypervel/bus, which provides five distinct lifecycle hooks for monitoring and responding to batch execution progress. It covers the purpose of each callback type, when they are invoked during batch execution, and how to configure them. For information about creating and dispatching batches, see Creating and Managing Batches. For information about nested batch structures, see Nested Batches and Chaining.

Overview of Batch Callbacks

The batch system provides five callback types that execute at different points during batch lifecycle:

Callback Type	Trigger Condition	Invocation Count	Primary Use Case
before	After batch storage, before job dispatch	Once	Initialize resources, send notifications
progress	After each job completes successfully	Multiple (per job)	Update progress indicators, logging
then	After all jobs complete successfully	Once	Success notifications, cleanup
catch	On first job failure	Once	Error handling, alerts
finally	After all jobs finish (success or failure)	Once	Guaranteed cleanup, final notifications

Callbacks are registered on the PendingBatch instance using fluent method chaining, then stored with the batch record for later execution.

Sources: src/PendingBatch.php69-164 src/Batch.php139-278

Callback Registration Methods

The before Callback

The before callback executes immediately after the batch is persisted to storage but before any jobs are dispatched. This is the only callback that runs synchronously during the dispatch() call.

Implementation Details:

• Registered via PendingBatch::before() src/PendingBatch.php69-76
• Stored in $options['before'] array src/PendingBatch.php71-73
• Closures are wrapped in SerializableClosure for persistence
• Invoked during PendingBatch::store() src/PendingBatch.php329-339
• Exceptions are caught and reported without failing batch creation

Sources: src/PendingBatch.php69-84 src/PendingBatch.php325-342

The progress Callback

The progress callback executes after each individual job completes successfully. This provides real-time feedback as the batch executes.

Implementation Details:

• Registered via PendingBatch::progress() src/PendingBatch.php89-96
• Stored in $options['progress'] array src/PendingBatch.php91-93
• Invoked by Batch::recordSuccessfulJob() src/Batch.php143-149
• Also invoked by Batch::recordFailedJob() if allowFailures() is true src/Batch.php231-237
• Receives the fresh batch instance and optionally the exception (on failure)

Sources: src/PendingBatch.php89-104 src/Batch.php139-149 src/Batch.php231-237

The then Callback

The then callback executes once when all jobs in the batch complete successfully. It only runs if no jobs failed (unless allowFailures() is true and all jobs finished).

Implementation Details:

• Registered via PendingBatch::then() src/PendingBatch.php109-116
• Stored in $options['then'] array src/PendingBatch.php111-113
• Invoked when $counts->pendingJobs === 0 src/Batch.php155-161
• Only executes if batch has "then" callbacks via hasThenCallbacks() src/Batch.php199-202
• Receives the fresh batch instance as sole parameter

Sources: src/PendingBatch.php109-124 src/Batch.php155-161 src/Batch.php199-202

The catch Callback

The catch callback executes when the first job in the batch fails. Subsequent failures do not trigger additional invocations.

Implementation Details:

• Registered via PendingBatch::catch() src/PendingBatch.php129-136
• Stored in $options['catch'] array src/PendingBatch.php131-133
• Invoked when $counts->failedJobs === 1 src/Batch.php239-245
• Only executes if batch has "catch" callbacks via hasCatchCallbacks() src/Batch.php267-270
• Receives both the batch instance and the exception that caused the failure

Sources: src/PendingBatch.php129-144 src/Batch.php239-245 src/Batch.php267-270

The finally Callback

The finally callback executes when all jobs have finished, regardless of success or failure. This is guaranteed to run exactly once.

Implementation Details:

• Registered via PendingBatch::finally() src/PendingBatch.php149-156
• Stored in $options['finally'] array src/PendingBatch.php151-153
• Invoked when $counts->allJobsHaveRanExactlyOnce() returns true src/Batch.php163-169 src/Batch.php247-253
• Executes after both successful and failed job completion
• Receives batch instance and optionally the exception (may be null)

Sources: src/PendingBatch.php149-164 src/Batch.php163-169 src/Batch.php247-253

Batch Lifecycle State Machine

Sources: src/PendingBatch.php245-267 src/Batch.php139-170 src/Batch.php223-254

Callback Invocation Flow

Sources: src/PendingBatch.php69-164 src/Batch.php139-170 src/Batch.php223-254

Callback Execution Mechanics

Closure Serialization

Callbacks that are closures are automatically wrapped in SerializableClosure instances for persistence. This allows closures to be stored in the database and reconstituted during callback execution.

Implementation: Each callback registration method checks if the callback is a Closure instance and wraps it:

This pattern is consistent across all five callback methods src/PendingBatch.php71-73 src/PendingBatch.php91-93 src/PendingBatch.php111-113 src/PendingBatch.php131-133 src/PendingBatch.php151-153

Sources: src/PendingBatch.php69-164

Multiple Callbacks

Each callback type supports registering multiple handlers. They are stored in arrays and executed in registration order:

During execution, the callbacks are iterated using Collection::make() and each() src/Batch.php146-149 src/Batch.php158-160 src/Batch.php234-236 src/Batch.php242-244 src/Batch.php250-252

Sources: src/Batch.php139-254

Error Handling

Callback exceptions are caught and reported through the exception handler but do not fail the batch or prevent subsequent callbacks from executing.

Implementation: The invokeHandlerCallback() method wraps callback execution in a try-catch block src/Batch.php315-326:

Similarly, before callbacks are protected src/PendingBatch.php330-338

Sources: src/Batch.php315-326 src/PendingBatch.php329-339

Fresh Batch Instances

Callbacks receive fresh batch instances retrieved from the repository to ensure they have the latest state. This is critical because batch state (pending jobs, failed jobs, etc.) changes as jobs execute.

Implementation: Before invoking callbacks, the code calls $batch->fresh() src/Batch.php144 src/Batch.php156 src/Batch.php164 src/Batch.php232 src/Batch.php240 src/Batch.php248:

Sources: src/Batch.php139-254

Callback Signature Reference

Callback Type	Signature	Parameters
before	function (Batch $batch): void	$batch - Fresh batch instance
progress	function (Batch $batch, ?Throwable $e = null): void	$batch - Fresh batch instance $e - Exception (only on failure with allowFailures)
then	function (Batch $batch): void	$batch - Fresh batch instance
catch	function (Batch $batch, Throwable $e): void	$batch - Fresh batch instance $e - The exception from the failed job
finally	function (Batch $batch, ?Throwable $e = null): void	$batch - Fresh batch instance $e - Exception (may be null)

Sources: src/Batch.php315-326

Callback Timing and Job Counts

UpdatedBatchJobCounts

When jobs complete, the repository returns an UpdatedBatchJobCounts object that contains the updated counts. This object is used to determine which callbacks to invoke:

• recordSuccessfulJob() calls decrementPendingJobs() src/Batch.php141
• recordFailedJob() calls incrementFailedJobs() src/Batch.php225

The allJobsHaveRanExactlyOnce() method determines if the finally callbacks should execute src/Batch.php163 src/Batch.php247

Sources: src/Batch.php139-178 src/Batch.php223-262

Conditional Invocation Logic

Sources: src/Batch.php139-170 src/Batch.php223-254

Interaction with allowFailures Option

The allowFailures() configuration option affects callback behavior:

• When false (default): First job failure cancels the batch src/Batch.php227-229
• When true: Jobs continue executing after failures
• Progress callbacks execute on failures only if allowFailures() is true src/Batch.php231-237
• Then callbacks only execute if no jobs failed
• Catch callbacks execute on first failure regardless of allowFailures()
• Finally callbacks always execute when all jobs finish

Sources: src/Batch.php227-237 src/PendingBatch.php169-182 src/Batch.php207-210

Complete Lifecycle Example

Sources: src/PendingBatch.php245-342 src/Batch.php139-170