Merge branch 'release/1.2.2'

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] - 2018-01-13
+
+### Added
+- Implemented Webhooks handling
+- Implemented `webhook` and `webhooks` methods in the `Descriptor` facade
+
 ## [1.2.1] - 2018-01-03
 
 ### Fixed
@@ -45,7 +51,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Fixed
 - Package keywords at composer.json
 
-[Unreleased]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.2.2...HEAD
+[1.2.2]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/brezzhnev/atlassian-connect-core/compare/v1.0.2...v1.1.0

README.md

@@ -216,6 +216,83 @@ public function viewIssue(string $key): array
 }
 ```
 
+### Webhooks
+
+The plugin provides a way to handle incoming webhooks, it uses Laravel Events so you can use habitual way to use them.
+
+> If you don't familiar with Laravel Events, please take a look at [Laravel Docs](https://laravel.com/docs/5.5/events)
+
+There are two ways to define webhook listeners:
+
+1\. Define listeners in the `config/plugin.php`
+
+``` php
+'webhooks' => [
+    'jira:issue_updated' => \App\Listeners\Webhooks\Issue\Created::class,
+    ...
+]
+```
+
+2\. Define listeners using the `Webhook` facade, for example:
+
+``` php
+Webhook::listen('jira:issue_created', function(\Illuminate\Http\Request $request) {
+    // ...
+});
+```
+
+As you can see, you can define event listener as a closure or as a string in Laravel-like syntax:
+
+``` php
+Webhook::listen('jira:issue_created', \App\Listeners\Webhooks\Issue\Created::class);
+Webhook::listen('jira:issue_created', 'App\Listeners\Webhooks\Issue\Created@handle');
+```
+
+#### Example listener
+
+``` php
+<?php
+
+namespace App\Listeners\Webhooks\Issue;
+
+use Illuminate\Http\Request;
+use AtlassianConnectCore\Models\Tenant;
+
+class Created
+{
+    /**
+     * Create the event listener.
+     *
+     * @return void
+     */
+    public function __construct()
+    {
+        //
+    }
+
+    /**
+     * Handle incoming webhook
+     *
+     * @param \Illuminate\Http\Request $request
+     * @param \AtlassianConnectCore\Models\Tenant $tenant
+     *
+     * @return void
+     */
+    public function handle(Request $request, Tenant $tenant)
+    {
+        // Access the order using $event->order...
+    }
+}
+```
+
+> Your event listeners may also type-hint any dependencies they need on their constructors. 
+All event listeners are resolved via the Laravel service container, so dependencies will be injected automatically.
+
+The handling method have the following parameters:
+
+1. `$request` - Request instance with Webhooks payload.
+1. `$tenant` - Authenticated Tenant model instance.
+
 ### Console commands
 
 * `plugin:install` is a helper command that creates "dummy" tenant with fake data and publishes package resources (config, views, assets)

composer.json

@@ -52,7 +52,8 @@
                 "AtlassianConnectCore\\ServiceProvider"
             ],
             "aliases": {
-                "Descriptor": "AtlassianConnectCore\\Facades\\Descriptor"
+                "Descriptor": "AtlassianConnectCore\\Facades\\Descriptor",
+                "Webhook": "AtlassianConnectCore\\Facades\\Webhook"
             }
         }
     },

config/plugin.php

@@ -114,5 +114,15 @@
      |
      */
 
-    'safeDelete' => true
+    'safeDelete' => true,
+
+    /*
+     |--------------------------------------------------------------------------
+     | The webhook listeners
+     |--------------------------------------------------------------------------
+     |
+     | You can define here listeners of the webhook events
+     |
+     */
+    'webhooks' => []
 ];

src/Descriptor.php

@@ -10,9 +10,11 @@
 class Descriptor
 {
     /**
+     * Descriptor contents
+     *
      * @var array
      */
-    private $contents = [];
+    protected $contents = [];
 
     /**
      * Descriptor constructor.
@@ -21,7 +23,7 @@ class Descriptor
      */
     public function __construct(array $contents = [])
     {
-        $this->contents = (!$contents ? $this->defaultContents() : $contents);
+        $this->contents = (empty($contents) ? $this->defaultContents() : $contents);
     }
 
     /**
@@ -177,6 +179,49 @@ public function base()
         return $this;
     }
 
+    /**
+     * Add or replace a webhook
+     *
+     * @param string $name
+     * @param string $url
+     */
+    public function webhook(string $name, string $url)
+    {
+        $webhooks = $this->get('modules.webhooks', []);
+
+        // Go through existing webhooks and if there is a webhook with the same name, just replace a url
+        foreach ($webhooks as $key => $webhook) {
+            if(array_get($webhook, 'event') === $name) {
+                $this->set("modules.webhooks.$key.url", $url);
+                return;
+            }
+        }
+
+        $webhooks[] = [
+            'event' => $name,
+            'url' => $url
+        ];
+
+        $this->set('modules.webhooks', $webhooks);
+    }
+
+    /**
+     * Define multiple webhooks
+     *
+     * [
+     *   'jira:issue_created' => '/webhook-handler-url',
+     *   ...
+     * ]
+     *
+     * @param array $webhooks
+     */
+    public function webhooks(array $webhooks)
+    {
+        foreach ($webhooks as $name => $url) {
+            $this->webhook($name, $url);
+        }
+    }
+
     /**
      * Default descriptor contents
      *

src/Facades/Webhook.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace AtlassianConnectCore\Facades;
+
+use Illuminate\Support\Facades\Facade;
+
+/**
+ * Class Webhook
+ *
+ * @package AtlassianConnectCore\Facades
+ */
+class Webhook extends Facade
+{
+    /**
+     * Get the registered name of the component.
+     *
+     * @return string
+     */
+    protected static function getFacadeAccessor()
+    {
+        return 'webhook';
+    }
+}

src/Http/Controllers/TenantController.php

@@ -2,8 +2,10 @@
 
 namespace AtlassianConnectCore\Http\Controllers;
 
+use Illuminate\Http\Request;
 use Illuminate\Routing\Controller;
 use AtlassianConnectCore\Facades\Descriptor;
+use AtlassianConnectCore\Facades\Webhook;
 use AtlassianConnectCore\Services\TenantService;
 
 /**
@@ -77,4 +79,19 @@ public function disabled(\AtlassianConnectCore\Http\Requests\DisabledRequest $re
     {
         event(new \AtlassianConnectCore\Events\Disabled($request));
     }
+
+    /**
+     * Handle an incoming webhook
+     *
+     * @param string $name Event name
+     *
+     * @param Request $request
+     */
+    public function webhook(string $name, Request $request)
+    {
+        Webhook::fire($name, [
+            'tenant' => \Illuminate\Support\Facades\Auth::user(),
+            'request' => $request
+        ]);
+    }
 }

src/Http/routes.php

@@ -9,6 +9,7 @@
     Route::group(['middleware' => 'jwt'], function () {
         Route::post('enabled', 'TenantController@enabled')->name('enabled');
         Route::post('uninstalled', 'TenantController@uninstalled')->name('uninstalled');
+        Route::post('webhook/{name}', 'TenantController@webhook')->name('webhook');
 
         Route::get('hello', 'SampleController@index')->name('hello');
     });

src/ServiceProvider.php

@@ -32,6 +32,7 @@ public function boot()
         $this->loadMigrations();
         $this->loadConsoleCommands();
         $this->loadViews();
+        $this->loadWebhooks();
     }
 
     /**
@@ -102,12 +103,23 @@ protected function loadViews()
         $this->loadViewsFrom(__DIR__ . '/../resources/views', 'plugin');
     }
 
+    /**
+     * Load webhook listeners
+     */
+    protected function loadWebhooks()
+    {
+        foreach (config('plugin.webhooks', []) as $webhook => $listener) {
+            \AtlassianConnectCore\Facades\Webhook::listen($webhook, $listener);
+        }
+    }
+
     /**
      * Register package facades
      */
     protected function registerFacades()
     {
         $this->app->bind('descriptor', Descriptor::class);
+        $this->app->bind('webhook', Webhook::class);
     }
 
     /**