houlokmah/laravel-tenancy-batch-fix

Fixes the DatabaseBatchRepository stale connection singleton problem in multi-tenant Laravel apps using stancl/tenancy

dev-main 2026-03-17 08:44 UTC

Requires

• php: ^8.0
• illuminate/bus: ^10.0|^11.0|^12.0
• illuminate/queue: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• stancl/tenancy: ^3.0

Requires (Dev)

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

MIT

• houlokmah

• queue
• laravel
• batch
• multi-tenant
• tenancy
• stancl
• DatabaseBatchRepository

README

Zero-config fix for the DatabaseBatchRepository stale connection problem in multi-tenant Laravel apps using stancl/tenancy.

If you've ever seen this error in your queue workers:

Call to a member function prepare() on null

...on DatabaseBatchRepository after the first job succeeds but subsequent jobs fail — this package fixes it.

The Problem

There are two layers to this bug:

Layer 1: Connection purging

QueueTenancyBootstrapper calls DB::purge('tenant') after each job completes. This destroys the PDO instance on the cached connection object, setting it to null.

Layer 2: Deferred singleton override

Laravel's BusServiceProvider implements DeferrableProvider. It doesn't load until BatchRepository is first resolved. When it does load, it registers BatchRepository and DatabaseBatchRepository as singletons — overriding any bind() you may have set up in your own service provider.

The combined effect

Job 1 starts
  → Tenancy bootstraps, connects to tenant DB
  → BatchRepository singleton created (holds live connection) ✅
  → Job completes
  → QueueTenancyBootstrapper calls DB::purge() → PDO set to null

Job 2 starts
  → Tenancy bootstraps new tenant DB
  → BatchRepository resolves → returns SAME singleton (stale connection, null PDO)
  → prepare() on null 💥

The same issue occurs in the scheduler when using runForMultiple() to iterate through tenants.

The Solution

This package applies a three-pronged fix:

1. register() — Binds BatchRepository and DatabaseBatchRepository using bind() instead of singleton(), creating a fresh instance per resolution.

2. TenancyBootstrapped listener — Re-applies the bind() after each tenant switch, clearing any cached singleton that the deferred BusServiceProvider may have created.

3. Queue::before() listener — Safety net that re-binds before every queued job, covering central-connection jobs where TenancyBootstrapped doesn't fire.

Why this works

• Container::bind() calls dropStaleInstances(), which removes any cached singleton
• The closure inside bind() resolves DB::connection() at resolution time (not registration time), so it always gets the current live tenant connection
• Queue::before() fires after QueueTenancyBootstrapper initializes the tenant (because the bootstrapper registers its listener during the register phase, while our Queue::before registers in boot)

Installation

composer require houlokmah/laravel-tenancy-batch-fix

Then restart your queue workers:

php artisan queue:restart

That's it. The package uses Laravel's auto-discovery — no manual service provider registration needed.

Configuration (Optional)

For most apps, zero configuration is needed. If you need to customize the batch table name or database connection:

php artisan vendor:publish --tag=tenancy-batch-fix-config

This publishes config/tenancy-batch-fix.php:

return [
    // Override batch table name (default: falls through to queue.batching.table)
    'table' => null,

    // Override database connection (default: falls through to queue.batching.database)
    'connection' => null,
];

Execution Flow

Before (broken)

Worker boots → AppServiceProvider bind()
            → Job 1 resolves BatchRepository
            → BusServiceProvider loads (deferred) → overrides with singleton()
            → Job 1 succeeds
            → DB::purge() → PDO = null
            → Job 2 resolves BatchRepository → gets stale singleton → 💥

After (fixed)

Worker boots → TenancyBatchFixServiceProvider bind()
            → Job 1 resolves BatchRepository → fresh instance ✅
            → BusServiceProvider loads (deferred) → overrides with singleton()
            → Job 1 succeeds
            → DB::purge() → PDO = null
            → Queue::before fires → re-binds (clears stale singleton)
            → TenancyBootstrapped fires → re-binds again (belt + suspenders)
            → Job 2 resolves BatchRepository → fresh instance ✅

Requirements

• PHP 8.0+
• Laravel 10, 11, or 12
• stancl/tenancy v3.x

How It Works (Deep Dive)

Why bind() clears the singleton

Laravel's Container::bind() method calls dropStaleInstances($abstract), which removes the key from both $this->instances (where singletons are cached) and $this->aliases. This is the mechanism that clears the stale DatabaseBatchRepository singleton.

Why BusServiceProvider overrides our binding

BusServiceProvider implements DeferrableProvider and declares BatchRepository::class in its provides() method. Laravel's deferred provider mechanism means the provider only loads when one of its provided abstracts is first resolved. At that point, its register() method runs and calls singleton(), which replaces any bind() we set up earlier.

Why Queue::before fires after tenancy initialization

QueueTenancyBootstrapper::__constructStatic() registers its JobProcessing listener during the service provider register phase (via Event::listen). Our Queue::before() registers during boot(), which runs later. Since Laravel dispatches listeners in registration order, the tenancy bootstrapper's listener fires first (initializing the tenant connection), and our listener fires second (re-binding with the now-live connection).

Why we bind both abstracts

BusServiceProvider::registerBatchServices() registers singletons for both BatchRepository::class and DatabaseBatchRepository::class. If we only override BatchRepository, the deferred provider's cached singleton for DatabaseBatchRepository could still surface. Overriding both ensures no stale instances remain.

Testing

composer test

Or directly:

vendor/bin/phpunit

License

The MIT License (MIT). See LICENSE for details.