Download the PHP package bytetcore/queue-unique-runner without Composer

bytetcore/queue-unique-runner

Ensure your Laravel queue jobs run on only one server instance at a time using distributed locking. Includes automatic crash recovery, lock heartbeat, and supports both Database and Redis drivers.

The Problem

When running multiple queue workers across different servers, sometimes you have jobs that must not run concurrently under any circumstances (e.g., end-of-day financial calculations, syncing large datasets with third-party APIs).

While Laravel's WithoutOverlapping middleware is great, if a server crashes midway through a job, the lock gets permanently stuck until manually cleared.

The Solution

queue-unique-runner provides robust distributed locking with:

• Heartbeat mechanism: Periodically extends the lock while the job is actively running.
• Crash recovery: If a server crashes or the worker is abruptly killed, the heartbeat stops, the lock expires automatically via TTL, and another server can safely retry the job.
• Per-class or Per-instance locking: Lock the entire job class, or lock per unique payload.

Installation

You can install the package via composer:

If using the Database driver (the default), publish and run the migrations:

Optionally, publish the config file:

Usage

Simply add the RunsOnUniqueRunner trait to your job:

Configuration per Job

You can override the default configuration for specific jobs by overriding these methods:

Drivers

Database (Default)

Creates a queue_unique_runner_locks table. Uses unique constraints to guarantee atomic locks.

It is recommended to periodically run the prune command to clean up expired locks from the database:

Redis

Uses SET NX EX commands and Lua scripts for atomic operations. Extremely fast and automatically handles expired lock cleanup.

Change your .env:

Requirements

• PHP 8.0+
• Laravel 9.0+
• (Optional but recommended) pcntl extension for Heartbeat functionality

Testing