timmylindh/laravel-batch-dispatcher

Batch Laravel queued jobs and queued event listeners into a single queued job dispatched at the end of the request.

v0.0.2 2025-08-30 21:38 UTC

Requires

• php: ^8.1||^8.2||^8.3
• illuminate/bus: ^10.0||^11.0||^12.0
• illuminate/contracts: ^10.0||^11.0||^12.0
• illuminate/events: ^10.0||^11.0||^12.0
• illuminate/http: ^10.0||^11.0||^12.0
• illuminate/queue: ^10.0||^11.0||^12.0
• illuminate/support: ^10.0||^11.0||^12.0

Requires (Dev)

• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^10.0.0||^9.0.0||^8.22.0
• pestphp/pest: ^3.0||^2.34
• pestphp/pest-plugin-laravel: ^3.0||^2.3

MIT

• Timmy Lindholm

• queue
• performance
• events
• dispatcher
• laravel
• batch
• jobs
• Batching

README

Batch queued jobs and queued event listeners into a single queued job. This reduces the number of queue requests by capturing multiple dispatches and sending them as one job that processes all items.

Installation

Requires:

• Laravel >= 10
• PHP >= 8.1

You can install the package via composer:

composer require timmylindh/laravel-batch-dispatcher

You can publish the config file with:

php artisan vendor:publish --tag="laravel-batch-dispatcher-config"

Usage

Behavior

• All calls to dispatch(), SomeJob::dispatch(), and Event::dispatch() will be buffered during the request.
• On terminate, the package queues a single wrapper job which in turn dispatches all buffered jobs and queued listeners.

Configuration

You can publish the config file with:

php artisan vendor:publish --tag="laravel-batch-dispatcher-config"

The batching behavior is controlled by config/batch-dispatcher.php:

return [
  "enabled" => env("BATCH_DISPATCHER_ENABLED", true),

  /**
   * In testing, avoid serializing jobs and run the wrapper immediately for assertions
   */
  "synchronous_testing" => env(
    "BATCH_DISPATCHER_SYNC_TESTING",
    env("APP_ENV") === "testing"
  ),

  /**
   * Maximum number of buffered items (jobs + queued listeners)
   * per wrapper job. When exceeded, multiple wrapper jobs will be dispatched.
   */
  "max_batch_size" => env("BATCH_DISPATCHER_MAX_SIZE", 10),

  /**
   * Enable the middleware to batch the requests.
   * Otherwise you will have to manually wrap the routes in the middleware.
   */
  "enable_middleware" => env("BATCH_DISPATCHER_ENABLE_MIDDLEWARE", true),
];

Middleware

Setting enable_middleware = true will automatically apply the batching to the api and web middleware groups. You can apply the batching to specific routes or groups by adding the BatchRequests middleware.

Notes

• Only instances of jobs implementing ShouldQueue and queued event listeners are batched.
• Per-job queue options (connection/queue/delay) are respected when listeners are enqueued by the wrapper. Jobs are dispatched as usual by the wrapper.

How it works

During the request, we intercept:

• Bus dispatches of ShouldQueue jobs and store the job instances in memory
• Event dispatches with queued listeners and capture their queued calls

On terminate, a single ProcessBatch job is queued. It then dispatches the buffered jobs and enqueues/invokes listeners.

Testing

composer test

Credits

• Timmy Lindholm
• All Contributors

License

The MIT License (MIT). Please see License File for more information.