Merge pull request #5 from mpbarlow/develop

Add support for chains and make it easier to override behaviour.

Author: mpbarlow

.gitignore

@@ -1,3 +1,4 @@
-/vendor
 composer.lock
 /.idea
+.phpunit.result.cache
+/vendor

README.md

@@ -1,33 +1,38 @@
 # Laravel Queue Debouncer
+
 ### Easy queue job debouncing
 
 ## Requirements
-* Laravel >= 6.0
-* An async queue driver
+
+- Laravel >= 6.0
+- An async queue driver
 
 **Note:** v2.0 requires at least Laravel 6. For Laravel 5.5 ..< 6.0 support, check out [v1.0.2](https://github.com/mpbarlow/laravel-queue-debouncer/tree/1.0.2)
 
 ## Installation
+
 `composer require mpbarlow/laravel-queue-debouncer`
 
 ## Background
-This package allows any queue job 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 actually be ran once.
 
-For example, imagine you want to send an email each time a user changes their contact details, but you don’t want to spam them if they make several changes in a short space of time. Debouncing the job with a five minute wait would ensure they only receive a single email, no matter how many changes they make within that five minutes.
+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.
 
-Version 2.0 is a complete rewrite and brings numerous improvements to the capabilities and ergonomics of the package, as well as thorough test coverage.
+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
-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` or a closure. `$wait` accepts any argument that the `delay` method on a dispatch accepts (i.e. a `DateTimeInterface` or a number of seconds). 
+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
-There are several ways to initiate debouncing of a job:
+
+There are several ways to use the debouncer:
 
 #### Dependency Injection
+
 ```php
 use App\Jobs\MyJob;
 use Mpbarlow\LaravelQueueDebouncer\Debouncer;
@@ -45,6 +50,7 @@ class MyController
 ```
 
 #### Facade
+
 ```php
 use App\Jobs\MyJob;
 use Mpbarlow\LaravelQueueDebouncer\Facade\Debouncer;
@@ -53,15 +59,14 @@ Debouncer::debounce(new MyJob, 30);
 ```
 
 #### Helper function
+
 ```php
 use App\Jobs\MyJob;
 
 debounce(new MyJob(), 30);
 ```
 
-Of course, you may substitute the job class for a closure.
-
-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. 
+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:
 
@@ -102,7 +107,8 @@ Hello!
 ```
 
 ## Customising Behaviour
-This package provides a few knobs and dials to customise things to your needs. To override the default behaviour, you should publish the config file:
+
+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"
@@ -111,25 +117,54 @@ php artisan vendor:publish --provider="Mpbarlow\LaravelQueueDebouncer\ServicePro
 This will copy `queue_debouncer.php` to your config directory.
 
 ### Cache key provider
-To support multiple jobs being debounced, the package generates a unique key in the cache for each job type. This key is used as a lookup when the wait for a given dispatch expires, to determine whether the job should be ran or not.
 
-The default implementation works as follows:
-* For class-based jobs, use the fully-qualified class name
-* For closure-based jobs, compute the SHA1 hash of a reflected representation of the closure
-* Prepend the `cache_prefix` value from the config, separated by a colon (‘:’)
+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 the default behaviour works for you, but you’d like to use a different cache prefix, you may simply override that value.
+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.
 
-Alternatively, you can provide your own class to produce a key for a given job. This is useful in cases where you have jobs that are implemented as different classes but should be considered the same job for the purposes of debouncing.
+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:
 
-Your provider class must 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—it will not be added automatically.
+```php
+$debouncer
+    ->usingCacheKeyProvider(new CustomCacheKeyProvider())
+    ->debounce($job, 10);
+```
 
-**Note:** Because of the limited ways we have to produce a value representation of a closure, only the _exact same closure_ will produce the same cache key. So, while closures originating from the same line in the same file will produce the same key on subsequent requests, two closures with the same content dispatched from different places will not.
+If you provide a closure, it may only be be hot-swapped:
+
+```php
+$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
-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 inserted, 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 via the config. As with the cache key provider, your class must implement  `Mpbarlow\LaravelQueueDebouncer\Contracts\UniqueIdentifierProvider`.
+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:
+
+```php
+$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
+
 This package is open-source software provided under the [The MIT License](https://opensource.org/licenses/MIT).

src/Contracts/CacheKeyProvider.php

@@ -5,12 +5,11 @@
 
 
 use Closure;
-use Illuminate\Foundation\Bus\Dispatchable;
 
 interface CacheKeyProvider
 {
     /**
-     * @param Dispatchable|Closure $job
+     * @param \Illuminate\Foundation\Bus\Dispatchable|\Illuminate\Foundation\Bus\PendingChain|Closure $job
      * @return string
      */
     public function getKey($job): string;

src/Debouncer.php

@@ -5,14 +5,13 @@
 
 
 use Closure;
-use DateInterval;
-use DateTimeInterface;
 use Illuminate\Bus\Queueable;
 use Illuminate\Foundation\Bus\Dispatchable;
-use Illuminate\Foundation\Bus\PendingDispatch;
 use Illuminate\Support\Facades\Cache;
 use Mpbarlow\LaravelQueueDebouncer\Contracts\CacheKeyProvider;
 use Mpbarlow\LaravelQueueDebouncer\Contracts\UniqueIdentifierProvider;
+use Mpbarlow\LaravelQueueDebouncer\Support\ClosureCacheKeyProvider;
+use Mpbarlow\LaravelQueueDebouncer\Support\ClosureUniqueIdentifierProvider;
 
 use function dispatch;
 
@@ -35,9 +34,35 @@ public function __construct(
     }
 
     /**
-     * @param Dispatchable|Closure $job
-     * @param DateTimeInterface|DateInterval|int|null $wait
-     * @return PendingDispatch
+     * @param CacheKeyProvider|Closure $provider
+     * @return $this
+     */
+    public function usingCacheKeyProvider($provider): self
+    {
+        $this->keyProvider = $provider instanceof Closure
+            ? new ClosureCacheKeyProvider($provider)
+            : $provider;
+
+        return $this;
+    }
+
+    /**
+     * @param UniqueIdentifierProvider|Closure $provider
+     * @return $this
+     */
+    public function usingUniqueIdentifierProvider($provider): self
+    {
+        $this->idProvider = $provider instanceof Closure
+            ? new ClosureUniqueIdentifierProvider($provider)
+            : $provider;
+
+        return $this;
+    }
+
+    /**
+     * @param Dispatchable|\Illuminate\Foundation\Bus\PendingChain|Closure $job
+     * @param \DateTimeInterface|\DateInterval|int|null $wait
+     * @return \Illuminate\Foundation\Bus\PendingDispatch
      */
     public function __invoke($job, $wait)
     {
@@ -52,9 +77,9 @@ public function __invoke($job, $wait)
     }
 
     /**
-     * @param Dispatchable|Closure $job
-     * @param DateTimeInterface|DateInterval|int|null $wait
-     * @return PendingDispatch
+     * @param Dispatchable|\Illuminate\Foundation\Bus\PendingChain|Closure $job
+     * @param \DateTimeInterface|\DateInterval|int|null $wait
+     * @return \Illuminate\Foundation\Bus\PendingDispatch
      */
     public function debounce($job, $wait)
     {

src/DispatcherFactory.php

@@ -5,7 +5,7 @@
 
 
 use Closure;
-use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Foundation\Bus\PendingChain;
 use Illuminate\Support\Facades\Cache;
 
 use function dispatch;
@@ -18,7 +18,7 @@ class DispatcherFactory
      * If we used a class as the dispatcher, we would have to check whether the job is a closure ourselves, and
      * serialise it if it was.
      *
-     * @param Dispatchable|Closure $job
+     * @param \Illuminate\Foundation\Bus\Dispatchable|PendingChain|Closure $job
      * @param string $key
      * @param string $identifier
      * @return Closure
@@ -29,7 +29,11 @@ public function makeDispatcher($job, $key, $identifier): Closure
             if (Cache::get($key) == $identifier) {
                 Cache::forget($key);
 
-                dispatch($job);
+                if ($job instanceof PendingChain) {
+                    $job->dispatch();
+                } else {
+                    dispatch($job);
+                }
             }
         };
     }

src/Facade/Debouncer.php

@@ -8,7 +8,7 @@
 
 /**
  * @see \Mpbarlow\LaravelQueueDebouncer\Debouncer
- * @method static \Illuminate\Foundation\Bus\PendingDispatch debounce(\Illuminate\Foundation\Bus\Dispatchable|\Closure $job, \DateTimeInterface|\DateInterval|int|null $wait)
+ * @method static \Illuminate\Foundation\Bus\PendingDispatch debounce(\Illuminate\Foundation\Bus\Dispatchable|\Illuminate\Foundation\Bus\PendingChain|\Closure $job, \DateTimeInterface|\DateInterval|int|null $wait)
  */
 class Debouncer extends Facade
 {

src/Support/ClosureCacheKeyProvider.php

@@ -0,0 +1,25 @@
+<?php
+
+
+namespace Mpbarlow\LaravelQueueDebouncer\Support;
+
+
+use Closure;
+use Mpbarlow\LaravelQueueDebouncer\Contracts\CacheKeyProvider as CacheKeyProviderContract;
+
+use function config;
+
+class ClosureCacheKeyProvider implements CacheKeyProviderContract
+{
+    protected $provider;
+
+    public function __construct(Closure $provider)
+    {
+        $this->provider = $provider;
+    }
+
+    public function getKey($job): string
+    {
+        return config('queue_debouncer.cache_prefix') . ':' . ($this->provider)($job);
+    }
+}

src/Support/ClosureUniqueIdentifierProvider.php

@@ -0,0 +1,23 @@
+<?php
+
+
+namespace Mpbarlow\LaravelQueueDebouncer\Support;
+
+
+use Closure;
+use Mpbarlow\LaravelQueueDebouncer\Contracts\UniqueIdentifierProvider as UniqueIdentifierProviderContract;
+
+class ClosureUniqueIdentifierProvider implements UniqueIdentifierProviderContract
+{
+    protected $provider;
+
+    public function __construct(Closure $provider)
+    {
+        $this->provider = $provider;
+    }
+
+    public function getIdentifier(): string
+    {
+        return ($this->provider)();
+    }
+}

src/Support/SerializingCacheKeyProvider.php

@@ -0,0 +1,18 @@
+<?php
+
+
+namespace Mpbarlow\LaravelQueueDebouncer\Support;
+
+
+use Mpbarlow\LaravelQueueDebouncer\Contracts\CacheKeyProvider as CacheKeyProviderContract;
+
+use function config;
+use function sha1;
+
+class SerializingCacheKeyProvider implements CacheKeyProviderContract
+{
+    public function getKey($job): string
+    {
+        return config('queue_debouncer.cache_prefix') . ':' . sha1(\Opis\Closure\serialize($job));
+    }
+}

src/Support/helpers.php

@@ -1,14 +1,12 @@
 <?php
 
-use Illuminate\Foundation\Bus\Dispatchable;
-use Illuminate\Foundation\Bus\PendingDispatch;
 use Mpbarlow\LaravelQueueDebouncer\Debouncer;
 
 if (! function_exists('debounce')) {
     /**
-     * @param Dispatchable|Closure $job
+     * @param \Illuminate\Foundation\Bus\Dispatchable|\Illuminate\Foundation\Bus\PendingChain|Closure $job
      * @param DateTimeInterface|DateInterval|int|null $wait
-     * @return PendingDispatch
+     * @return \Illuminate\Foundation\Bus\PendingDispatch
      */
     function debounce($job, $wait)
     {