dovutuan/laravel-sji

Queue middleware: only one job runs at a time per instance

dev-master 2025-08-25 15:32 UTC

Requires

• php: >=8.0
• illuminate/console: ^7.0|^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• squizlabs/php_codesniffer: ^3.13

MIT

• dovutuan

• queue
• middleware
• laravel
• job
• lock
• mutex
• concurrency
• unique
• instance
• overlapping
• single-job

README

Laravel Queue middleware: on each instance (host/container), only one job runs at a time (per key). Lock scope: instance_id + key — so it will not block jobs on other instances.

Installation

composer require dovutuan/laravel-sji
php artisan vendor:publish --tag=config --provider="Dovutuan\\Sji\\ServiceProvider"

.env (Redis recommended):

CACHE_STORE=redis
SJI_LOCK_STORE=redis
SJI_TTL=600
SJI_BLOCK_FOR=0
SJI_INSTANCE_RESOLVER=hostname
# SJI_INSTANCE_ID=app-1   # optional, for stable ID in containers

Usage

use Illuminate\\Contracts\\Queue\\ShouldQueue;
use Dovutuan\\Sji\\SjiMiddleware;

class HeavyJob implements ShouldQueue
{
    public function __construct(public string $group = 'global') {}

    public function middleware(): array
    {
        return [
            // per-instance lock: one job at a time on this instance
            new SjiMiddleware(
                key: "job:{$this->group}",
                ttl: 600,
                blockFor: 0,
                store: 'redis',
                releaseAfter: 10
            ),
        ];
    }

    public function handle(): void
    {
        // ...
    }
}

Artisan Command

Generate and write a new SJI_INSTANCE_ID to your .env file:

php artisan sji:make-instance-id

Options:

• --force or -f → overwrite existing value.

Example:

$ php artisan sji:make-instance-id
SJI_INSTANCE_ID set to: 9a0b8e0e-8d1d-4d7c-b229-1f4fbc9f1d2a

.env will now contain:

SJI_INSTANCE_ID=9a0b8e0e-8d1d-4d7c-b229-1f4fbc9f1d2a

Difference from WithoutOverlapping

• WithoutOverlapping: locks cluster-wide (if all workers share the same cache), blocking across all instances.
• SjiMiddleware: locks per instance → ensures only one job per instance, but allows jobs to run in parallel across multiple instances.

Notes

• Set TTL ≥ max job runtime + buffer to avoid early lock expiration.
• In containerized environments, consider setting SJI_INSTANCE_ID explicitly for a stable ID.
• Can be combined with ShouldBeUnique / ShouldBeUniqueUntilProcessing to prevent duplicate enqueues, and idempotent job design for retry safety.
• For Horizon, ensure timeout and retry_after are configured properly.

Development

Test

Uses Orchestra Testbench.

composer install
vendor/bin/phpunit

License

MIT