Update docs

Author: mpbarlow

README.md

@@ -1,112 +1,135 @@
 # Laravel Queue Debouncer
-### Really easy debouncing of Laravel queue jobs via a wrapper job
+### Easy queue job debouncing
 
 ## Requirements
-* PHP >= 7.0
-* Laravel >= 5.5
-* A correctly configured asynchronous queue driver (tested with Redis and database drivers, but anything should work fine)
-* A correctly configured cache 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.
+
+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.
+
 ## Usage
-The package comes in two main parts: a wrapper job `Debounce` that is dispatched immediately, and an abstract superclass
-`DebouncedJob` that your debounced jobs should extend.
-
-`Debounce`’s constructor takes at least two arguments; `string $debounceable`, which is the fully-qualified class name of
-the job you wish to debounce, and `int $waitTime`, which is the time in seconds that will be waited after the last dispatch of the job before it is fired. Any additional arguments will be passed directly to the constructor of the debounced job.
-`Debounce` is also responsible for generating the unique ID that will be assigned to your job; out of the box it uses
-[ramsey/uuid](https://github.com/ramsey/uuid), which ships with Laravel, to generate a random UUID4 string. However, if
-this does not suit your needs, you can subclass `Debounced` and override `generateUniqueId()`.
-
-If you would prefer to implement your own wrapper class, the interface `DebouncesJobs` contains the methods your
-customer wrapper must implement and call from its `handle()` method. You are responsible for caching the unique ID in a
-way that the debounced job can retreive, however the `ProvidesCacheKey` trait contains the default implementation used by
-both `Debounce` and `DebouncedJob`.
-
-`DebouncedJob` is the class that your debounced jobs should extend. It receives the unique ID from the
-wrapper job via the constructor (if you need to override the default constructor be sure to call `parent::__construct($uniqueId)`
-— `$uniqueId` is always the first argument your constructor receives, followed by any additional parameters you may have
-passed). By default it takes responsibility for your job’s `handle()` method, checking whether the job should run, and
-if so, calling the `debounced()` method. This is the method you should implement with your job logic. If the job should
-not run, it is automatically deleted and `debounced()` is never called.
-
-If you can’t subclass `DebouncedJob` for your jobs, this package also provides a trait `InteractsWithDebouncer`,
-which provides the default implementation for `handle()`, and a method `shouldRun()` which returns a boolean value
-indicating whether the job should run.
-
-If you prefer or need to implement your logic in the normal `handle()` method (for example if you need access to objects
-via dependency injection), override the provided implementation and call `shouldRun()` manually to determine your course
-of action.
-
-## Example
-SimpleDebouncedJob.php
+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). 
+
+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:
+
+#### Dependency Injection
 ```php
-...
+use App\Jobs\MyJob;
+use Mpbarlow\LaravelQueueDebouncer\Debouncer;
 
-public function debounced()
+class MyController
 {
-    echo "Hello, I am debounced. I have no data though :(\n";
+    public function doTheThing(Debouncer $debouncer)
+    {
+        $debouncer->debounce(new MyJob(), 30);
+
+        // The class is also invokable:
+        $debouncer(new MyJob(), 30);
+    }
 }
 ```
 
-DebouncedJobWithExtraArguments.php
+#### Facade
 ```php
-...
+use App\Jobs\MyJob;
+use Mpbarlow\LaravelQueueDebouncer\Facade\Debouncer;
 
-    protected $some;
-    protected $extra;
-    protected $arguments;
+Debouncer::debounce(new MyJob, 30);
+```
 
-    public function __construct($uniqueId, $some, $extra, $arguments)
-    {
-        // We must make sure to provide the superclass constructor with the unique ID
-        parent::__construct($uniqueId);
+#### Helper function
+```php
+use App\Jobs\MyJob;
 
-        $this->some = $some;
-        $this->extra = $extra;
-        $this->arguments = $arguments;
-    }
+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. 
+
+For example, assuming the following code was ran at exactly 9am:
 
-    public function debounced()
+```php
+class MyJob
+{
+    use Dispatchable;
+
+    public function handle()
     {
-        echo "Hello, I am debounced. I have {$this->some} {$this->extra} {$this->arguments} though! :D\n";
+        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));
 ```
 
-```php
-dispatch(new Debounce(SimpleDebouncedJob::class, 10));
-sleep(1);
-dispatch(new Debounce(SimpleDebouncedJob::class, 10));
-sleep(1);
-dispatch(new Debounce(SimpleDebouncedJob::class, 10));
-sleep(1);
-
-dispatch(new Debounce(DebouncedJobWithExtraArguments::class, 10, 'some', 'extra', 'arguments'));
-sleep(1);
-dispatch(new Debounce(DebouncedJobWithExtraArguments::class, 10, 'some', 'extra', 'arguments'));
-sleep(1);
-dispatch(new Debounce(DebouncedJobWithExtraArguments::class, 10, 'some', 'extra', 'arguments'));
-sleep(1);
+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
+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:
+
+```
+php artisan vendor:publish --provider="Mpbarlow\LaravelQueueDebouncer\ServiceProvider"
+```
+
+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 (‘:’)
+
+If the default behaviour works for you, but you’d like to use a different cache prefix, you may simply override that value.
 
-`SimpleDebouncedJob` and `DebouncedJobWithExtraArguments` will each run approximately 10 seconds after their last dispatch,
-respectively, producing the following output:
+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.
 
-![](README/debouncer.jpg)
+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.
 
-It's worth noting that if your job does not produce any output it may appear that it is running every single time. In a
-sense it is, but only to determine whether or not execution should continue. The actual `debounced()` method containing
-your logic is only executed when the bouncing has settled.
+**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.
 
-See also the included Examples folder.
+### 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.
 
-## Potential Issues
-Race conditions with certain drivers, particularly when multiple processes work the queue, or when wait times are very
-short, can mean that the job that executes is not always the last one that was dispatched. It will still only execute
-once, but it is important to bear this in mind if your job is strictly dependent on dispatch order.
+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`.
 
-## License
+## Licence
 This package is open-source software provided under the [The MIT License](https://opensource.org/licenses/MIT).

docs/debouncer.jpg

@@ -4,16 +4,11 @@
 namespace Mpbarlow\LaravelQueueDebouncer\Facade;
 
 
-use Closure;
-use DateInterval;
-use DateTimeInterface;
-use Illuminate\Foundation\Bus\Dispatchable;
-use Illuminate\Foundation\Bus\PendingDispatch;
 use Illuminate\Support\Facades\Facade;
 
 /**
  * @see \Mpbarlow\LaravelQueueDebouncer\Debouncer
- * @method static PendingDispatch debounce(Dispatchable|Closure $job, DateTimeInterface|DateInterval|int|null $wait)
+ * @method static \Illuminate\Foundation\Bus\PendingDispatch debounce(\Illuminate\Foundation\Bus\Dispatchable|\Closure $job, \DateTimeInterface|\DateInterval|int|null $wait)
  */
 class Debouncer extends Facade
 {

src/Facade/Debouncer.php

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

src/Support/helpers.php

@@ -4,6 +4,7 @@
 namespace Mpbarlow\LaravelQueueDebouncer\Tests;
 
 
+use Illuminate\Foundation\Bus\Dispatchable;
 use Mpbarlow\LaravelQueueDebouncer\Support\CacheKeyProvider;
 use ReflectionFunction;
 
@@ -74,4 +75,6 @@ public function it_generates_a_consistent_key_for_closures()
     }
 }
 
-class DummyJob {}
+class DummyJob {
+    use Dispatchable;
+}