PHPackages                             mpbarlow/laravel-queue-debouncer - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. mpbarlow/laravel-queue-debouncer

ActiveLibrary[Queues & Workers](/categories/queues)

mpbarlow/laravel-queue-debouncer
================================

A wrapper job for debouncing other queue jobs.

3.2.0(1mo ago)63714.4k↑34.1%11[1 issues](https://github.com/mpbarlow/laravel-queue-debouncer/issues)1MITPHPPHP ^8.2CI passing

Since Jun 7Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mpbarlow/laravel-queue-debouncer)[ Packagist](https://packagist.org/packages/mpbarlow/laravel-queue-debouncer)[ RSS](/packages/mpbarlow-laravel-queue-debouncer/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (17)Used By (1)

Laravel Queue Debouncer
=======================

[](#laravel-queue-debouncer)

### Easy queue job debouncing

[](#easy-queue-job-debouncing)

Requirements
------------

[](#requirements)

- Laravel >= 11.0
- An async queue driver

### Previous releases

[](#previous-releases)

- For Laravel 10.0 ..< 11.0 support, check out [v3.0.0](https://github.com/mpbarlow/laravel-queue-debouncer/releases/tag/3.0.0)
- For Laravel 6.0 ..< 10.0 support, check out [v2.6.0](https://github.com/mpbarlow/laravel-queue-debouncer/releases/tag/2.6.0)
- For Laravel 5.5 ..< 6.0 support, check out [v1.0.2](https://github.com/mpbarlow/laravel-queue-debouncer/tree/1.0.2)

Installation
------------

[](#installation)

```
$ composer require mpbarlow/laravel-queue-debouncer
```

Background
----------

[](#background)

This package allows any queue job or chain in your Laravel application to be debounced, meaning that no matter how many times it’s dispatched within the specified timeout window, it will only run once.

For example, imagine you dispatch a job to rebuild a cache every time a record is updated, but the job is resource intensive. Debouncing the job with a five minute wait would ensure that the cache is only rebuilt once, five minutes after you finish making changes.

Usage
-----

[](#usage)

Debounced jobs can largely be treated like any other dispatched job. The debouncer takes two arguments, the actual `$job` you want to run, and the `$wait` period.

As with a regular dispatch, `$job` can be either a class implementing `Illuminate\Foundation\Bus\Dispatchable`, a chain, or a closure. `$wait` accepts any argument that the `delay` method on a dispatch accepts (i.e. a `DateTimeInterface` or a number of seconds).

The debouncer returns an instance of `Illuminate\Foundation\Bus\PendingDispatch`, meaning the debouncing process itself may be assigned to a different queue or otherwise manipulated.

### Calling the debouncer

[](#calling-the-debouncer)

There are several ways to use the debouncer:

#### Dependency Injection

[](#dependency-injection)

```
use App\Jobs\MyJob;
use Mpbarlow\LaravelQueueDebouncer\Debouncer;

class MyController
{
    public function doTheThing(Debouncer $debouncer)
    {
        $debouncer->debounce(new MyJob(), 30);

        // The class is also invokable:
        $debouncer(new MyJob(), 30);
    }
}
```

#### Facade

[](#facade)

```
use App\Jobs\MyJob;
use Mpbarlow\LaravelQueueDebouncer\Facade\Debouncer;

Debouncer::debounce(new MyJob, 30);
```

#### Helper function

[](#helper-function)

```
use App\Jobs\MyJob;

debounce(new MyJob(), 30);
```

#### Trait

[](#trait)

```
use Illuminate\Bus\Queueable;
use Illuminate\Foundation\Bus\Dispatchable;
use Mpbarlow\LaravelQueueDebouncer\Traits\Debounceable;

class MyJob {
    use Debounceable, Dispatchable, Queueable;
}

MyJob::debounce('foo', 'bar', 'baz', 30);
```

When monitoring the queue, you will see an entry for the package’s internal dispatcher each time the debounced job is queued, but the job itself will only run once, when the final wait time has expired.

For example, assuming the following code was ran at exactly 9am:

```
class MyJob
{
    use Dispatchable;

    public function handle()
    {
        echo “Hello!\n”;
    }
}

$job = new MyJob();

debounce($job, now()->addSeconds(5));
sleep(3);

debounce($job, now()->addSeconds(5));
sleep(3);

debounce($job, now()->addSeconds(5));
```

you should expect the following activity on your queue:

```
[2020-03-11 09:00:05][vHmqrBYeLtK3Lbiq5TsTZxBo2igaCZHC] Processing: Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:05][vHmqrBYeLtK3Lbiq5TsTZxBo2igaCZHC] Processed:  Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:08][LXdzLvilh5qhew7akNDnibCjaXksG81X] Processing: Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:08][LXdzLvilh5qhew7akNDnibCjaXksG81X] Processed:  Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:11][MnPIqk5fCwXjiVzuwPjkkOdPPBn0xR4d] Processing: Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:11][MnPIqk5fCwXjiVzuwPjkkOdPPBn0xR4d] Processed:  Closure (DispatcherFactory.php:28)
[2020-03-11 09:00:11][I2hvBoCB71qZQeD4umn5dd90zJUCAlJ5] Processing: App\Jobs\MyJob
Hello!
[2020-03-11 09:00:11][I2hvBoCB71qZQeD4umn5dd90zJUCAlJ5] Processed:  App\Jobs\MyJob

```

Customising Behaviour
---------------------

[](#customising-behaviour)

This package provides a few hooks to customise things to your needs. To override the default behaviour, you should publish the config file:

```
php artisan vendor:publish --provider="Mpbarlow\LaravelQueueDebouncer\ServiceProvider"

```

This will copy `queue_debouncer.php` to your config directory.

### Cache key provider

[](#cache-key-provider)

To identify the job being debounced, the package generates a unique key in the cache for each job type.

Two cache key providers are included:

- `Mpbarlow\LaravelQueueDebouncer\Support\CacheKeyProvider` (default): uses the config's `cache_prefix` value with either: the fully-qualified class name for class-based jobs; or a SHA1 hash of the closure for closure jobs.
- `Mpbarlow\LaravelQueueDebouncer\Support\SerializingCacheKeyProvider`: uses the config's `cache_prefix` value with a SHA1 hash of the serialized job. If you want to debounce jobs based on factors beyond their class name (for example, some internal state), this is the provider to use. This is also required if you need to debounce chains, as the default provider will debounce *all* chains dispatched by your application as if they are the same job, regardless of what jobs are contained within.

Alternatively, you can provide your own class or closure to cover any other behaviour you might need:

If you provide a class, it should implement `Mpbarlow\LaravelQueueDebouncer\Contracts\CacheKeyProvider`. Please note that your class is responsible for fetching and prepending the cache prefix should you still desire this behaviour.

Class-based providers may be globally registered as the default provider by changing the `cache_key_provider` value in the config. Alternatively, you may "hot-swap" the provider using the `usingUniqueIdentifierProvider` method:

```
$debouncer
    ->usingCacheKeyProvider(new CustomCacheKeyProvider())
    ->debounce($job, 10);
```

If you provide a closure, it may only be be hot-swapped:

```
$debouncer
    ->usingCacheKeyProvider(fn () => 'my custom key')
    ->debounce($job, 10);
```

Closure providers automatically have their value prefixed by the configured `cache_prefix`. To override this behaviour, implement a class-based provider that accepts a closure in its constructor, then calls it in its `getKey` method.

### Unique identifier provider

[](#unique-identifier-provider)

Each time a debounced job is dispatched, a unique identifier is stored against the cache key for the job. When the wait time expires, if that identifier matches the value of the current job, the debouncer knows that no more recent instances of the job have been dispatched, and therefore it is safe to dispatch it.

The default implementation produces a UUID v4 for each dispatch. If you need to override this you may do so in the same manner as cache key providers, globally registering a class under the `unique_identifier_provider` key in the config, or hot-swapping using the `usingUniqueIdentifierProvider` method:

```
$debouncer
    ->usingUniqueIdentifierProvider(new CustomUniqueIdentifierProvider())
    ->debounce($job, 10);

$debouncer
    ->usingUniqueIdentifierProvider(fn () => 'my custom identifier')
    ->debounce($job, 10);
```

Class-based providers should implement `Mpbarlow\LaravelQueueDebouncer\Contracts\UniqueIdentifierProvider`.

Licence
-------

[](#licence)

This package is open-source software provided under the [The MIT License](https://opensource.org/licenses/MIT).

###  Health Score

65

—

FairBetter than 99% of packages

Maintenance88

Actively maintained with recent releases

Popularity52

Moderate usage in the ecosystem

Community19

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 76.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~203 days

Recently: every ~251 days

Total

15

Last Release

55d ago

Major Versions

1.x-dev → 2.0.02020-03-11

2.6.0 → 3.0.02024-12-08

PHP version history (5 changes)1.0.0PHP >=7.0

2.0.0PHP ^7.2

2.2.0PHP ^7.2|^8.0

3.0.0PHP ^8.1

3.1.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/d9e88bc78df3c63972c2d666b004290ea5c44b01f33bd523a03fbd32cb33c493?d=identicon)[mpbarlow](/maintainers/mpbarlow)

---

Top Contributors

[![mpbarlow](https://avatars.githubusercontent.com/u/26557284?v=4)](https://github.com/mpbarlow "mpbarlow (29 commits)")[![onlime](https://avatars.githubusercontent.com/u/2759561?v=4)](https://github.com/onlime "onlime (6 commits)")[![a-bashtannik](https://avatars.githubusercontent.com/u/2712350?v=4)](https://github.com/a-bashtannik "a-bashtannik (1 commits)")[![roblesterjr04](https://avatars.githubusercontent.com/u/6423115?v=4)](https://github.com/roblesterjr04 "roblesterjr04 (1 commits)")[![scybulski](https://avatars.githubusercontent.com/u/10341108?v=4)](https://github.com/scybulski "scybulski (1 commits)")

---

Tags

laravelqueuejobdebounce

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mpbarlow-laravel-queue-debouncer/health.svg)

```
[![Health](https://phpackages.com/badges/mpbarlow-laravel-queue-debouncer/health.svg)](https://phpackages.com/packages/mpbarlow-laravel-queue-debouncer)
```

###  Alternatives

[imtigger/laravel-job-status

Laravel Job Status

5272.1M3](/packages/imtigger-laravel-job-status)[anourvalar/eloquent-serialize

Laravel Query Builder (Eloquent) serialization

11120.2M21](/packages/anourvalar-eloquent-serialize)[pmatseykanets/artisan-beans

Easily manage your Beanstalkd job queues right from the Laravel artisan command

4482.1k](/packages/pmatseykanets-artisan-beans)[renoki-co/horizon-exporter

Export Laravel Horizon metrics using this Prometheus exporter.

24152.7k](/packages/renoki-co-horizon-exporter)[tochka-developers/queue-promises

Promises for Laravel queue jobs

1912.3k](/packages/tochka-developers-queue-promises)[convenia/pigeon

3233.0k](/packages/convenia-pigeon)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)