Creating and Managing Batches

Purpose and Scope

This document explains how to create and configure batches in the hypervel/bus system. It covers the PendingBatch configuration API, batch option management, dynamic job addition, and the role of BatchFactory in instantiating Batch objects. For information about batch callbacks and lifecycle management, see Batch Callbacks and Lifecycle. For nested batch structures, see Nested Batches and Chaining.

---

Overview

Batch creation in hypervel/bus follows a builder pattern where batches are configured via the PendingBatch class before being dispatched. The process involves:

1. Creating a PendingBatch instance (typically via Bus::batch())
2. Configuring batch options (name, queue, connection, failure handling)
3. Adding jobs to the batch
4. Dispatching the batch, which stores it via BatchRepository and creates a Batch object

The following diagram illustrates the batch creation and dispatch flow:

Sources: src/PendingBatch.php245-267 src/BatchFactory.php26-40

---

The PendingBatch Class

The PendingBatch class serves as the configuration API for batches before they are dispatched. It is instantiated with a collection of jobs and provides a fluent interface for setting batch options.

Constructor and Properties

Property	Type	Description
$container	ContainerInterface	Hyperf DI container for resolving dependencies
$jobs	Collection	The jobs that belong to the batch
$name	string	The batch name (defaults to empty string)
$options	array	Configuration options (queue, connection, callbacks, etc.)

The constructor is defined at src/PendingBatch.php44-48 and accepts the container and a Collection of jobs.

Sources: src/PendingBatch.php24-48

---

Configuration Methods

The PendingBatch class provides methods to configure various aspects of batch execution. All configuration methods return $this to enable method chaining.

Basic Configuration

Setting the Batch Name

Sets a human-readable name for the batch. This name is stored with the batch and can be used for identification and monitoring purposes.

Implementation: src/PendingBatch.php187-192

Specifying Queue Connection

Specifies which queue connection the batched jobs should use. The connection can be retrieved via connection() method.

Implementation: src/PendingBatch.php197-210

Specifying Queue Name

Specifies which queue the batched jobs should run on. Accepts a string queue name or a BackedEnum (which is converted to its value via enum_value()). The queue can be retrieved via queue() method.

Implementation: src/PendingBatch.php215-228

Failure Handling

Allowing Failures

Indicates that the batch should continue processing even when individual jobs fail. By default, batches cancel remaining jobs when any job fails. This method allows you to change that behavior.

The failure handling state can be checked via allowsFailures() method at src/PendingBatch.php179-182

Implementation: src/PendingBatch.php169-174

Custom Options

Adding Custom Options

Allows adding arbitrary data to the batch's options array. This is useful for passing custom metadata or configuration that your application may need.

Implementation: src/PendingBatch.php233-238

Configuration Methods Summary

Method	Parameters	Purpose
name()	string $name	Set the batch name
onConnection()	string $connection	Set queue connection
onQueue()	BackedEnum|string|null $queue	Set queue name
allowFailures()	bool $allowFailures = true	Allow batch to continue on failures
withOption()	string $key, mixed $value	Add custom option data

Sources: src/PendingBatch.php187-238

---

Adding Jobs to Batches

The add() Method

Jobs can be added to a batch dynamically using the add() method:

This method accepts:

• A single job object
• An array of job objects
• Any iterable collection of job objects

The implementation at src/PendingBatch.php55-64 wraps single objects into an array using Arr::wrap() and then pushes each job into the internal $jobs collection.

Adding Jobs at Different Stages

Jobs can be added at two different stages:

1. During PendingBatch Creation - Initial jobs passed to constructor
2. Before Dispatch - Additional jobs added via add() method
3. After Storage - Jobs added to the Batch object itself (handled by Batch::add())

The following diagram shows the job addition flow:

Sources: src/PendingBatch.php44-64 src/PendingBatch.php245-267

---

Batch Instantiation with BatchFactory

The BatchFactory class is responsible for creating Batch object instances. It follows the factory pattern to encapsulate the complex construction of Batch objects.

BatchFactory Structure

Sources: src/BatchFactory.php1-42

Factory Method Parameters

The make() method at src/BatchFactory.php26-40 accepts the following parameters:

Parameter	Type	Description
$repository	BatchRepository	Repository for batch persistence
$id	string	Unique batch identifier
$name	string	Batch name
$totalJobs	int	Total number of jobs in batch
$pendingJobs	int	Number of jobs not yet processed
$failedJobs	int	Number of failed jobs
$failedJobIds	array	Array of failed job IDs
$options	array	Batch configuration options
$createdAt	CarbonImmutable	Batch creation timestamp
$cancelledAt	CarbonImmutable|null	Batch cancellation timestamp
$finishedAt	CarbonImmutable|null	Batch completion timestamp

The factory constructs a new Batch instance by passing the QueueFactory (injected in the factory's constructor) and all provided parameters to the Batch constructor.

Sources: src/BatchFactory.php16-40

---

Dispatching Batches

Once configured, a PendingBatch is dispatched to begin batch execution. The dispatch process stores the batch, adds jobs, and fires events.

Dispatch Methods

Standard Dispatch

The primary dispatch method performs the following steps:

1. Resolves BatchRepository from the container
2. Stores the batch configuration via store() method
3. Adds jobs to the stored batch
4. Fires BatchDispatched event
5. Returns the Batch instance

If an exception occurs during job addition, the batch is deleted from the repository and the exception is re-thrown.

Implementation: src/PendingBatch.php245-267

Deferred Dispatch

This method dispatches the batch after the HTTP response is sent to the browser. It:

1. Stores the batch immediately
2. Uses Coroutine::defer() to schedule job addition after response
3. Returns the Batch instance immediately

The deferred dispatch is useful for improving perceived response time by not blocking on job queuing.

Implementation: src/PendingBatch.php272-281

Conditional Dispatch

These methods allow conditional dispatching based on a boolean value or closure result:

• dispatchIf() dispatches when condition is true
• dispatchUnless() dispatches when condition is false

Both return null when the condition prevents dispatch.

Implementation: src/PendingBatch.php307-318

The Store Process

The protected store() method at src/PendingBatch.php323-340 handles batch persistence:

1. Calls $repository->store($this) to persist the PendingBatch
2. Executes all registered "before" callbacks (see Batch Callbacks and Lifecycle)
3. Returns the stored Batch instance

Any exceptions thrown during callback execution are reported via the ExceptionHandler but do not interrupt the store process.

Sources: src/PendingBatch.php323-340

---

Batch Dispatch Flow

The complete batch creation and dispatch flow integrates all the components discussed:

Sources: src/PendingBatch.php245-340

---

Code Entity Reference

The following table maps the high-level concepts discussed in this page to their concrete implementations:

Concept	Primary Code Entity	Location
Batch Configuration API	PendingBatch class	src/PendingBatch.php24-341
Batch Instantiation	BatchFactory::make()	src/BatchFactory.php26-40
Job Collection Management	PendingBatch::add()	src/PendingBatch.php55-64
Batch Name Configuration	PendingBatch::name()	src/PendingBatch.php187-192
Queue Configuration	PendingBatch::onQueue()	src/PendingBatch.php215-220
Connection Configuration	PendingBatch::onConnection()	src/PendingBatch.php197-202
Failure Handling	PendingBatch::allowFailures()	src/PendingBatch.php169-174
Standard Dispatch	PendingBatch::dispatch()	src/PendingBatch.php245-267
Deferred Dispatch	PendingBatch::dispatchAfterResponse()	src/PendingBatch.php272-281
Conditional Dispatch	PendingBatch::dispatchIf/Unless()	src/PendingBatch.php307-318
Batch Persistence	PendingBatch::store()	src/PendingBatch.php323-340

Sources: src/PendingBatch.php1-341 src/BatchFactory.php1-42

---

Integration Points

The PendingBatch system integrates with several other components:

Component	Integration Point	Purpose
ContainerInterface	Constructor injection	Resolves dependencies
BatchRepository	dispatch() and store()	Persists batch state
EventDispatcherInterface	dispatch() method	Fires BatchDispatched event
QueueFactory	Via BatchFactory	Creates queue connections for job dispatch
Batch	Returned from dispatch()	Manages running batch
Collection	$jobs property	Stores jobs to be batched

Sources: src/PendingBatch.php17-18 src/PendingBatch.php44-48 src/PendingBatch.php247 src/PendingBatch.php261-264 src/BatchFactory.php17-18