[13.x] Add debounceable queued jobs

[matthewnessworthy]

Summary

Adds debouncing for queued jobs — when the same job is dispatched multiple times within a time window, only the last dispatch executes. Earlier dispatches are silently discarded at execution time.

Apply the #[DebounceFor] attribute to any ShouldQueue job, or debounce at the dispatch site. No interface needed.

How it works

1. Dispatch: A random owner token is written to the cache (last-writer-wins). The job is delayed by the debounce window.
2. Execute: The worker checks if the job's token still matches the cache. If yes, it runs. If a newer dispatch overwrote the token, the job is deleted and a JobDebounced event fires.
3. Fail-open: If the cache entry is missing (eviction, cache:clear), the job executes rather than being silently lost.

Uses plain cache put/get — not locks. Locks enforce mutual exclusion (first-writer-wins), which is the opposite of what debounce needs.

Comparison with ShouldBeUnique

	ShouldBeUnique	#[DebounceFor]
Which dispatch wins?	First	Last
Rejected dispatches	Not queued	Queued but skipped at execution
Check point	Dispatch time	Execution time
Storage	Cache locks	Plain cache key
Missing token	N/A	Fail-open (job runs)
Manager	UniqueLock	DebounceLock

Combining both on the same job throws LogicException — first-wins and last-wins are mutually exclusive.

Usage

Attribute-based (on the job class)

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

#[DebounceFor(30)]
class RebuildSearchIndex implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function __construct(public int $documentId) {}

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

    public function handle(): void
    {
        SearchIndex::rebuild($this->documentId);
    }
}

// User edits a document 10 times in 30 seconds — only the last dispatch runs
RebuildSearchIndex::dispatch($document->id);

Call-site debouncing

Debounce any job at the dispatch site without modifying the job class:

// Debounce a plain job — no attribute needed on the class
dispatch(new SyncExternalData($accountId))->debounceFor(30);

// Override the class attribute at dispatch time
dispatch(new RebuildSearchIndex($docId))->debounceFor(10);

Max-wait cap

Prevent a frequently re-dispatched job from being deferred indefinitely. After maxWait seconds from the first dispatch, the job executes immediately:

#[DebounceFor(30, maxWait: 120)]
class SyncDashboard implements ShouldQueue { ... }

// Or at the dispatch site:
dispatch(new SyncDashboard)->debounceFor(30)->maxDebounceWait(120);

Override delay via method

The debounceFor() method takes precedence over the attribute value:

#[DebounceFor(30)]
class RebuildSearchIndex implements ShouldQueue
{
    public function debounceFor(): int
    {
        return $this->priority === 'high' ? 5 : 30;
    }
}

Custom cache store

public function debounceVia(): \Illuminate\Contracts\Cache\Repository
{
    return Cache::store('redis');
}

Listen for superseded jobs

Event::listen(JobDebounced::class, function (JobDebounced $event) {
    Log::info('Debounced: '.get_class($event->command));
});

Design notes

• Owner-aware release: DebounceLock::release() only removes the token if it still belongs to the caller, preventing a finished job from wiping a newer dispatch's token.
• Superseded jobs are fully discarded: A superseded job fires JobDebounced and is deleted — it does not dispatch chain links or record batch success, since no work was performed.
• Transaction rollback: Debounce tokens are released on DB transaction rollback, matching the ShouldBeUnique pattern.
• Cache TTL: Set to 10× the debounce window (min 300s) for garbage collection only — correctness doesn't depend on it.
• Priority: call-site ->debounceFor() > debounceFor() method > #[DebounceFor] attribute.

[github-actions]

Thanks for submitting a PR!

Note that draft PRs are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[bert-w]

Good stuff. The only thing i dont like is the empty interface and the method_exists checks, but perhaps those are inherent to the way Laravel jobs are written. It makes it non-intuitive to fill in functions and I have to either check the code or read the docs.

[matthewnessworthy]

@bert-w thanks for taking the time to review the code, both points you mentioned are consistent with Laravel and the similar feature ShouldBeUnique

[matthewnessworthy]

@taylorotwell any thoughts on this? happy to make adjustments as needed

[kohlerdominik]

Something that I missed, and I didn't even know it. I would love to see something like this added to the Framework.

I just noticed in ShouldBeUniqueUntilProcessing that retries affect the lock in a potential unpleasant way and tried a fix with #59567. In your test cases, I also see testing only for $tries = 1. Did you implement a strategy for retries, and would it possibly also fit ShouldBeUniqueUntilProcessing?

[matthewnessworthy]

@kohlerdominik retries shouldn't be a problem, if it gets bounced back into the queue it will re-check whether it is still the owner of this job and either continue processing or abort (if it's no longer the owner)
I don't think Debounceable sufferers from the same problem as ShouldBeUniqueUntilProcessing as it's using get/set on the cache instead of lock. Additionally, the issue you are describing is almost an inherent flaw because as soon as the processing starts it is no longer unique

[taylorotwell]

I feel like there is too much going on here. Interface, attribute, middleware - I'm not sure which one to use. Just have an attribute imo.

[matthewnessworthy]

@taylorotwell No problem, PR updated with your review, should be significantly simpler now