Queue Job Execution Control

How to use ShouldBeUnique, ShouldBeUniqueUntilProcessing, and DebounceFor to control duplicate execution and burst dispatches of queued jobs.

Overview

Laravel’s queue system provides two strategies for controlling job execution: Unique Jobs and Debounced Jobs. Both prevent unnecessary work when the same job is dispatched multiple times, but they work differently.

Feature	Interface / Attribute	Purpose
Unique Jobs	ShouldBeUnique	Ensures only one instance of a job exists on the queue
Unique Until Processing	ShouldBeUniqueUntilProcessing	Holds the unique lock only until processing begins
Debounced Jobs	#[DebounceFor]	When a job is dispatched many times in a short window, only the latest dispatch runs

Unique jobs and debounced jobs are mutually exclusive. A job using the DebounceFor attribute should not implement ShouldBeUnique.

---

Unique Jobs — ShouldBeUnique

Prevents duplicate dispatches while an instance of the job is already on the queue.

<?php

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUnique;

class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    // No additional methods required
}

While UpdateSearchIndex is on the queue (or being processed), any new dispatches of the same job will be silently ignored.

Scoping Uniqueness with a Key — UniqueFor + uniqueId()

When the same job class handles different entities (e.g., product A vs. product B), define a uniqueId() method to scope the uniqueness constraint.

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Queue\Attributes\UniqueFor;

#[UniqueFor(3600)] // Auto-release the lock after 1 hour
class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    public function __construct(public readonly int $productId)
    {
    }

    public function uniqueId(): string
    {
        return (string) $this->productId;
    }
}

• The value returned by uniqueId() becomes the cache lock key.
• #[UniqueFor(seconds)] sets a timeout after which the lock is automatically released — a failsafe for stuck jobs.

Customizing the Cache Driver — uniqueVia()

To use a specific cache driver instead of the default:

use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;

public function uniqueVia(): Repository
{
    return Cache::driver('redis');
}

Unique Jobs require a cache driver that supports atomic locks: redis, database, memcached, dynamodb, file, or array.

---

ShouldBeUnique vs ShouldBeUniqueUntilProcessing

With ShouldBeUnique, the lock is held until the job completes or exhausts its retry attempts. This can be a problem in some scenarios.

Example: UpdateSearchIndex(product_id: 42) is on the queue. A worker picks it up and starts processing. You want to dispatch the same job again — but the lock is still held, so the new dispatch is ignored until processing finishes.

ShouldBeUniqueUntilProcessing releases the lock immediately before processing begins, allowing a new dispatch the moment a worker picks up the job.

<?php

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing;

class UpdateSearchIndex implements ShouldQueue, ShouldBeUniqueUntilProcessing
{
    // ...
}

Comparison

	ShouldBeUnique	ShouldBeUniqueUntilProcessing
Lock released	After completion / failure	Before processing begins
Dispatch while processing	Ignored	Accepted
Use case	Prevent all concurrency	Allow re-queue while processing

---

Debounced Jobs — #[DebounceFor]

The DebounceFor attribute was added in Laravel 13.

When the same job is dispatched many times in a short window, only the last dispatch executes. This mirrors the debounce pattern from frontend development.

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\DebounceFor;

#[DebounceFor(30)] // Only the last dispatch within 30 seconds runs
class UpdateSearchIndex implements ShouldQueue
{
    use Queueable;

    public function __construct(public readonly int $productId)
    {
    }

    public function debounceId(): string
    {
        return (string) $this->productId;
    }
}

• debounceId() identifies which dispatches are considered “the same job” (each productId is debounced independently).
• If UpdateSearchIndex for product 42 is dispatched 10 times within 30 seconds, only the last dispatch will run.

maxWait — Capping the Deferral Window

For frequently updated data, debouncing could postpone execution indefinitely. Set maxWait to cap how long a job can be deferred.

#[DebounceFor(30, maxWait: 120)]
class UpdateSearchIndex implements ShouldQueue
{
    use Queueable;
    // ...
}

In this example, the job will always run within 120 seconds of the first dispatch, even if new dispatches keep resetting the 30-second window.

Customizing the Cache Driver — debounceVia()

use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;

public function debounceVia(): Repository
{
    return Cache::driver('redis');
}

JobDebounced Event

When a job is superseded by a newer dispatch, Laravel fires Illuminate\Queue\Events\JobDebounced and removes the superseded job from the queue. Listen to this event for monitoring or logging.

---

Choosing the Right Approach

Use case	Recommendation
Running the same job twice is pointless	ShouldBeUnique
Prevent parallel execution entirely	ShouldBeUnique
Allow re-dispatch as soon as processing starts	ShouldBeUniqueUntilProcessing
User clicks save repeatedly — process once	#[DebounceFor]
Rebuild search index after bulk model updates	#[DebounceFor] + maxWait

---

Internal Implementation

Lock Key Format for Unique Jobs

When a ShouldBeUnique job is dispatched, Laravel acquires a cache atomic lock using the following key format:

laravel_unique_job:{JobClassName}:{uniqueId()}

If the lock is already held, the job is not added to the queue.

How Debounced Jobs Work

DebounceFor uses a cache entry to manage a “debounce window”. On each new dispatch:

1. The existing queued job is removed (JobDebounced event fired)
2. The new job is added to the queue with a delay equal to the debounce seconds
3. The debounce timer resets

When maxWait is specified, the timestamp of the first dispatch is also recorded, capping the total deferral time.

---

Reference

• Laravel Docs — Unique Jobs
• Laravel Docs — Debounced Jobs
• Illuminate\Contracts\Queue\ShouldBeUnique
• Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing
• Illuminate\Queue\Attributes\DebounceFor
• Illuminate\Queue\Attributes\UniqueFor