feat: improved flexibility and custom models

- Allow more flexibility in when webhooks are fired
- Allow implementors to use custom models
- Improved documentation
- Provide model contracts
- No longer need to manually implement webhook payload methods, can now use DeliversWebhooks trait

BREAKING: Changed existing model namespaces, and method names. Changed ShouldDeliverWebhooks contract.

Author: samatcd

README.md

@@ -10,10 +10,8 @@
 [![Packagist](https://poser.pugx.org/custom-d/webhook-registry/d/total.svg)](https://packagist.org/packages/custom-d/webhook-registry)
 [![Packagist](https://img.shields.io/packagist/l/custom-d/webhook-registry.svg)](https://packagist.org/packages/custom-d/webhook-registry)
 
-Package description: CHANGE ME
-
-@customD version
 
+A wrapper for [spatie/laravel-webhook-server](https://github.com/spatie/laravel-webhook-server) that provides a simple & flexible webhook registry, allows you to expose any Laravel Event as a webhook, and provides out-of-the-box logging of webhook results.
 
 ## Installation
 
@@ -22,23 +20,6 @@ Install via composer
 composer require custom-d/webhook-registry
 ```
 
-### Register Service Provider
-
-**Note! This and next step are optional if you use laravel>=5.5 with package
-auto discovery feature.**
-
-Add service provider to `config/app.php` in `providers` section
-```php
-CustomD\WebhookRegistry\ServiceProvider::class,
-```
-
-### Register Facade
-
-Register package facade in `config/app.php` in `aliases` section
-```php
-CustomD\WebhookRegistry\Facades\WebhookRegistry::class,
-```
-
 ### Publish Configuration File
 
 ```bash
@@ -47,28 +28,72 @@ php artisan vendor:publish --provider="CustomD\WebhookRegistry\ServiceProvider"
 
 ## Usage
 
-Implement the `CustomD\WebhookRegistry\Contracts\ShouldDeliverWebhooks` contract on any event you'd like to trigger a web-hook. This contract requires a `getWebhookPayload` method to be defined on your event, which will provide the payload details.
+### 1. Trigger registered webhooks via events
 
-Your payload must define a `body`, but can also define `tags` and `meta` information for passing to `Spatie\WebhookServer\WebhookCall`.
+Implement the `CustomD\WebhookRegistry\Contracts\ShouldDeliverWebhooks` contract on any Laravel Event, and you'll be able to register webhooks that will be fired on this event.
 
-```
+
+This contract defines several methods that need to be defined on your event, which will help provide the payload details.
+
+Method | Purpose
+-----|-----
+`getWebhookPayload` | Returns the payload to send to the Spatie Webhook call. Useful if you want to completely override the payload.
+`getWebhookContext` | Returns the payload `context` field. Useful if you want to set a different property. Defaults to returning the `->context` property from the event. If this property is `Arrayable`, we'll call `->toArray()`. You can overload this method on your event if you want to customise this behaviour.
+`getWebhookEventName` | Returns the event name you want to expose in the payload. Useful for endpoints who recieve multiple different types of event to determine how to handle calls. By default, this is the value of the `->webhookEventName` property from the event, otherwise we fall back to the event class name.
+`shouldDeliverWebhook` | Whether to deliver webhooks for this event. Defaults to true.
+
+Your payload must define a `body`, but can also define [tags](https://github.com/spatie/laravel-webhook-server#adding-tags) and [meta](https://github.com/spatie/laravel-webhook-server#adding-meta-information) information for passing to `Spatie\WebhookServer\WebhookCall`.
+
+```php
     /**
      * Get the payload for this webhook event
      */
     public function getWebhookPayload(): array
     {
-        $user = request()->user();
-
         return [
             'body' => [
                 'status' => $this->status,
-                'triggered_by' => $user && $user->toArray()
             ]
         ];
     }
 ```
 
-Create webhook endpoints uing `CustomD\WebhookRegistry\Model\WebhookEndpoint` or using the facade `WebhookRegistry::registerEndpoint` method, and associate a webhook event to an endpoint with the `CustomD\WebhookRegistry\Model\WebhookEvent` model, or using the facade `WebhookRegistry::registerEvent`.
+### 2. Register webooks
+
+Create webhook endpoints direction using the `CustomD\WebhookRegistry\Models\WebhookEndpoint` model, or use the facade `WebhookRegistry::registerEndpoint`.
+
+```php
+$endpoint = WebhookRegistry::registerEndpoint(
+  'https://webhook.site/custom/endpoint',
+  'My webhook endpoint name'
+);
+```
+
+By default, we'll verify SSL certificates on outgoing webhook connections. If you want to disable SSL verification, you can pass `false` to the `registerEndpoint` function.
+
+```php
+$endpoint = WebhookRegistry::registerEndpoint(
+  'https://localhost/webhook-test',
+  'My insecure endpoint',
+  false
+);
+```
+
+### 3. Bind events to an endpoint
+
+Associate a webhook event to an endpoint with the `CustomD\WebhookRegistry\Model\WebhookEvent` model, or using the facade `WebhookRegistry::registerEvent`.
+
+```
+$event = WebhookRegistry::registerEvent($webhook->id, 'App\Events\MyEvent');
+```
+
+## Models
+
+Customise the WebhookEvent model in order to add logic about when events should fire. In `config/webhook-registry.php` you will see the model name being used in `models` -> `events`. You can make your own model by implementing the `CustomD\WebhookRegistry\Models\Contracts\WebhookEventContract`.
+
+To specify which events are dispatchable in a given run, you must set a `scopeWhereDispatchable` on the model. This scope will be called before firing webhooks to endpoints with this event.
+
+By default this scope doesn't do anything.
 
 ## Security
 

config/webhook-registry.php

@@ -1,4 +1,9 @@
 <?php
 
 return [
+    'models' => [
+        'endpoint' => \CustomD\WebhookRegistry\Models\WebhookEndpoint::class,
+        'event'    => \CustomD\WebhookRegistry\Models\WebhookEvent::class,
+        'request'  => \CustomD\WebhookRegistry\Models\WebhookRequest::class,
+    ],
 ];

src/Contracts/ShouldDeliverWebhooks.php

@@ -2,12 +2,26 @@
 
 namespace CustomD\WebhookRegistry\Contracts;
 
-interface ShouldDeliverWebhooks {
+interface ShouldDeliverWebhooks
+{
 
      /**
-      * Get the webhook payload
-      *
-      * @return array
+      * Get the payload for this webhook event
       */
-     public function getWebhookPayload(): array;
+    public function getWebhookPayload(): array;
+
+    /**
+     * Get the payload context for this webhook event
+     */
+    public function getWebhookContext(): array;
+
+    /**
+     * Should we allow this event to deliver webhooks?
+     */
+    public function shouldDeliverWebhook(): bool;
+
+    /**
+     * Gets the event name.
+     */
+    public function getWebhookEventName(): string;
 }

src/Events/Traits/DeliversWebhooks.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace CustomD\WebhookRegistry\Events\Traits;
+
+use Illuminate\Contracts\Support\Arrayable;
+trait DeliversWebhooks
+{
+    /**
+     * Get the webhook payload
+     */
+    public function getWebhookPayload(): array
+    {
+        $user = request()->user();
+
+        return [
+            'body' => [
+                'event'        => $this->getWebhookEventName(),
+                'context'      => $this->getWebhookContext(),
+                'triggered_by' => $user ? $user->toArray() : null,
+            ]
+        ];
+    }
+
+    /**
+     * The value that will be returned in the `payload`
+     */
+    public function getWebhookContext(): array
+    {
+        if ($this->context instanceof Arrayable) {
+            return $this->context->toArray();
+        }
+
+        return $this->context ?? [];
+    }
+
+    /**
+     * Should we allow this event to deliver webhooks?
+     */
+    public function shouldDeliverWebhook(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Gets the event name.
+     */
+    public function getWebhookEventName(): string
+    {
+        return $this->webhookEventName ?? static::class;
+    }
+}

src/Listeners/GeneralEventSubscriber.php

@@ -10,16 +10,18 @@ class GeneralEventSubscriber
     /**
      * Register the listeners for the subscriber.
      *
-     * @param  \Illuminate\Events\Dispatcher  $events
+     * @param \Illuminate\Events\Dispatcher $events
      */
     public function subscribe($events)
     {
-        $events->listen('App\Events*', function ($eventName, array $payloads) {
-            foreach($payloads as $payload){
-                if(WebhookRegistry::has($eventName)){
-                    WebhookRegistry::trigger($eventName, $payload->getWebhookPayload());
+        $events->listen(
+            'App\Events*', function ($eventName, array $payloads) {
+                foreach($payloads as $payload){
+                    if($payload->shouldDeliverWebhook() && WebhookRegistry::has($eventName)) {
+                        WebhookRegistry::trigger($eventName, $payload->getWebhookPayload());
+                    }
                 }
             }
-        });
+        );
     }
 }

src/Listeners/LoggingEventSubscriber.php

@@ -2,8 +2,8 @@
 
 namespace CustomD\WebhookRegistry\Listeners;
 
+use CustomD\WebhookRegistry\Models\WebhookRequest;
 use Spatie\WebhookServer\Events\WebhookCallEvent;
-use CustomD\WebhookRegistry\Model\WebhookRequest;
 use Spatie\WebhookServer\Events\WebhookCallFailedEvent;
 use Spatie\WebhookServer\Events\WebhookCallSucceededEvent;
 use Spatie\WebhookServer\Events\FinalWebhookCallFailedEvent;
@@ -49,7 +49,7 @@ public function makeLogEntryFromEvent(WebhookCallEvent $event, string $status)
     /**
      * Register the listeners for the subscriber.
      *
-     * @param  \Illuminate\Events\Dispatcher  $events
+     * @param \Illuminate\Events\Dispatcher $events
      */
     public function subscribe($events)
     {

src/Model/WebhookEndpoint.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace CustomD\WebhookRegistry\Models\Contracts;
+
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+interface WebhookEndpointContract
+{
+
+     /**
+      * Get the events relationship
+      */
+    public function events(): HasMany;
+}

src/Model/WebhookEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace CustomD\WebhookRegistry\Models\Contracts;
+
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Builder;
+
+interface WebhookEventContract
+{
+
+     /**
+      * Get the endpoint relationship
+      */
+    public function endpoint(): BelongsTo;
+
+    /**
+     * A scope which determines whether this webhook endpoint will actually send the webhook.
+     */
+    public function scopeWhereDispatchable(Builder $builder): void;
+}