README
, (*1)
The library provides a Silex provider allowing you to execute your job on any
Github WebHook., (*2)
Installation
The library is distributed through Composer. So, fist,
install it :), (*3)
Create a composer.json file at the root directory of you project & put the following inside:, (*4)
``` json
{
"require": {
"widop/github-hook-provider": "*"
}
}, (*5)
As the library provides optional debugging, you can enable it by installing & registering the build-in Silex
[MonologServiceProvider](http://silex.sensiolabs.org/doc/providers/monolog.html):
``` json
{
"require": {
"widop/github-hook-provider": "*",
"monolog/monolog": "1.*"
}
}
Then, install the libraries:, (*6)
``` bash
$ composer install, (*7)
## Create your application
Now, we have everything locally, we can create the Silex application. Usually, we follow the following structure:
├── composer.json
├── composer.lock
├── src
│ └── ...
├── vendor
│ └── ...
└── web
└── hook.php, (*8)
The `web/hook.php` looks like:
``` php
<?php
require_once __DIR__.'/../vendor/autoload.php';
use Silex\Application;
$app = new Application();
// Optional dependencies
$app->register(new Silex\Provider\MonologServiceProvider(), array(/* ... */));
$app->run();
In this structure, the web directory is the vhost root directory of our application & the hook.php script is the
frontend controller managing our Github WebHook. So, if we create a vhost with my-domain.com as domain, we can put
http://my-domain.com/hook.php as Github Webhook., (*9)
The src directory should not exist yet. You can create it, we will need it in the next steps :), (*10)
Register the provider
The Silex application (which do nothing...) is up :), (*11)
Now, we need to register & configure the Wid'op Github Hook provider which will allow us to play with Github hooks. For
that, simply update the hook.php:, (*12)
``` php
<?php, (*13)
require_once DIR.'/../vendor/autoload.php';, (*14)
use Silex\Application;
use Widop\GithubHook\GithubHookProvider;, (*15)
$app = new Application();
$app->register(new GithubHookProvider(), array('github_hook.trusted_ips' => array('127.0.0.1', /* ... */)));
$app->run();, (*16)
When you go to the Github WebHook configuration accessible in your Github repo setting, you have a list of IPs which
can be trusted for Github WebHooks. The provider needs this list of IPs in order to secure the entry point. You can
obviously provide an empty array but **it is strongly not recommended!**
## Mount the controller
The Silex application with his provider is now well configured (but still do nothing...) :)
To finish the work, we need to mount the controller. One more time, update the `hook.php`:
``` php
<?php
require_once __DIR__.'/../vendor/autoload.php';
use Silex\Application;
use Widop\GithubHook\GithubHookProvider;
$githubHookProvider = new GithubHookProvider();
$app = new Application();
$app->register($githubHookProvider, array('github_hook.trusted_ips' => array('127.0.0.1', /* ... */)));
$app->mount('/', $githubHookProvider);
$app->run();
You're done! The set up is finished., (*17)
What next?
Next? It can be interesting to write our custom stuffs which will be executed when a valid hook is received... :), (*18)
How does it work?
As Silex itself, the provider is builded around the event dispatcher. When a hook is received & has been validated
against the IP firewall & the hook configuration, the github_hook event is fired & an event wrapping all informations
about the hook are propagated to all listeners/subscribers. So, we just have to write our event listener/subscriber., (*19)
You can register as many listener/subscribers you want & archive more complex use cases by playing with priorities or
event propagation..., (*20)
Write the Hook Subscriber
We recommend you to put your code, in the src directory:, (*21)
``` php
<?php
// src/Acme/MyHookSubscriber.php, (*22)
namespace Acme;, (*23)
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Widop\GithubHook\Event\Events;
use Widop\GithubHook\Event\HookEvent;, (*24)
class MyHookSubscriber implements EventSubscriberInterface
{
public function onHook(HookEvent $event)
{
$hook = $event->getHook();, (*25)
// Do your stuff...
}
public static function getSubscribedEvents()
{
return array(Events::HOOK => 'onHook');
}
}, (*26)
As we have added the `Acme` namespace, we need update the `composer.json` in order to autoload new classes:
``` json
{
"autoload": {
"psr-0": {
"Acme": "src/"
}
},
// ...
}
``` bash
$ composer update, (*27)
### Register the Hook Subscriber
Our hook subscriber is defined & it does our custom stuffs. Now, we need to register it on the event dispatcher. For
that, we have two solutions: Directly in the `hook.php` or through a Silex provider.
#### Direct
Register our hook subscriber in the `hook.php`:
``` php
$app['dispatcher']->addSubscriber(new Acme\MyHookSubscriber());
Silex Provider
Create our hook provider:, (*28)
``` php
<?php
// src/Acme/MyHookProvider.php, (*29)
namespace Acme;, (*30)
use Silex\Application;
use Silex\ServiceProviderInterface;, (*31)
class MyHookProvider implements ServiceProviderInterface
{
public function boot(Application $app)
{
$app['dispatcher']->addSubscriber(new MyHookSubscriber(/* Injects your own parameters/services */));
}, (*32)
public function register(Application $app)
{
// Register your own services or simply let it empty :)
}
}, (*33)
Then, register our hook provider in the `hook.php`:
``` php
$app->register(new Acme\MyHookProvider());
Contribute
We love contributors! The library is open source, if you'd like to contribute, feel free to propose a PR!, (*34)
License
The Wid'op Github Hook Silex Provider is under the MIT license. For the full copyright and license information, please
read the LICENSE file that was distributed
with this source code., (*35)
Wallogit.com
Widop