kamz8/laravel-batch-orchestrator

Dynamic chunking and batch orchestration for Laravel queued jobs.

v1.1.0 2026-07-14 09:57 UTC

Requires

• php: ^8.2|^8.3|^8.4
• illuminate/bus: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.5|^11.0|^12.0

MIT

• Kamil Żmijowski

Published on Packagist.org on 2026-07-16 09:37 UTC

README

Dynamic chunking and orchestration of Laravel Bus::batch() for long-running jobs (reports, exports), with optional progress tracking in Redis.

Requirements

• PHP ^8.2, ^8.3, or ^8.4
• Laravel ^10.0, ^11.0, ^12.0, or ^13.0 (illuminate/bus, illuminate/support)

See docs/COMPATIBILITY.md for the full PHP × Laravel support matrix and known exceptions.

Installation

composer require kamz8/laravel-batch-orchestrator

Requires a job_batches table and a queue connection that supports batching:

php artisan queue:batches-table
php artisan migrate

Publish the config if you need to change the progress TTL:

php artisan vendor:publish --tag=batch-orchestrator-config

Components

• Contracts\ChunkableTask — the task contract: getChunks(), getChunkJobClass(), queue(), onBatchFinished(), onBatchFailed().
• Services\BaseOrchestrator / Services\BatchProcessOrchestrator — dispatches the batch and calls the corresponding task method on completion/failure.
• Concerns\HasBatchProgress — trait for models that tracks percentage progress in Redis (chunks count toward 80%, the remainder is the merge stage).

Full API description (parameters, edge-case behavior) lives in the PHPDoc in src/. See docs/AI_GUIDE.md for a deeper guide on wiring up a new ChunkableTask.

Lifecycle events

The package dispatches plain Laravel events (Illuminate\Support\Facades\Event) at key points of a batch's orchestration and its buffered-payload operations — BatchOrchestrationStarted/Finished/Failed, BatchProgressUpdated, and four BufferedPayload* events. It never broadcasts, queues, or registers listeners for them; that is entirely up to the consuming application (logging, custom domain broadcasts, UI updates, metrics). See docs/LIFECYCLE_EVENTS.md for the full emission order, an event table, and integration examples.

Testing

composer install
vendor/bin/phpunit

License

Proprietary.