swop / github-webhook-bundle
Symfony bundle which aims to simplify GitHub web hook handling.
Installs: 363
Dependents: 0
Suggesters: 0
Security: 0
Stars: 6
Watchers: 2
Forks: 4
Open Issues: 1
Type:symfony-bundle
Requires
- php: >=5.4
- psr/http-message: ^1.0
- psr/log: ^1.0
- sensio/framework-extra-bundle: ^3.0
- swop/github-webhook: ^2.0
- symfony/config: ^2.3|^3.0
- symfony/dependency-injection: ^2.3|^3.0
- symfony/event-dispatcher: ^2.3|^3.0
- symfony/http-foundation: ^2.3|^3.0
- symfony/http-kernel: ^2.3|^3.0
- symfony/psr-http-message-bridge: ^1.0
- zendframework/zend-diactoros: ^1.3
Requires (Dev)
- phpunit/phpunit: ^4.5.0
This package is not auto-updated.
Last update: 2024-11-04 14:59:44 UTC
README
This bundle aiming to reduce complexity when creating GitHub web hooks apps.
Installation
The recommended way to install this bundle is through Composer:
composer require "swop/github-webhook-bundle"
Then, register the bundle into your AppKernel
class. Note that this bundle rely on the SensioFrameworkExtraBundle
bundle in order to work properly.
<?php class AppKernel extends Kernel { public function registerBundles() { $bundles = [ // ... new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(), new Swop\Bundle\GitHubWebHookBundle\GitHubWebHookBundle() ]; // ... } }
Usage
Simply use the GitHubWebHook
annotation in your controllers to mark them as GitHub web hook controllers
<?php namespace AppBundle\Controller; use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; use Swop\GitHubWebHook\Event\GitHubEvent; use Symfony\Bundle\FrameworkBundle\Controller\Controller; use Swop\Bundle\GitHubWebHookBundle\Annotation\GitHubWebHook; class DefaultController extends Controller { /** * @Route("/webhook", name="webhook") * * @GitHubWebHook(eventType="push") * @GitHubWebHook(eventType="pull_request") */ public function indexAction(GitHubEvent $gitHubEvent) { $payload = $gitHubEvent->getPayload(); // Request payload (array) $eventType = $gitHubEvent->getType(); // "pull" or "pull_request" // Do something depending on the payload & the event type... return ['status' => 'success']; } }
By declaring that your controller is a GitHub web hook, the bundle will make the following actions for you:
-
It will check if the incoming web hook event is supported by your controller. If it's not the case, a
400
JSON response will be automatically returned. -
It will verify that the incoming request has a correct signature, using the web hook specific secret (see "Annotation reference") or the default one (see "Bundle configuration reference"). If the request signature is invalid, a
403
JSON response will be automatically returned. -
It will build a
GitHubEvent
object which will be injected in the controller parameters. -
It will manage the serialization of the data you returned in your controller, and thus will send back a
200
JSON response to GitHub.
Configuration
Bundle configuration reference
github_webhook: default_secret: my_secret
default_secret
: Default secret to use on every hooks when validating the incoming request signature.
Annotation reference
Simple event type handling (will respond only to the push
event):
<?php /** * @GitHubWebHook(eventType="push") */
Multiple event types handling (will respond to the push
and pull_request
event):
<?php /** * @GitHubWebHook(eventType="push") * @GitHubWebHook(eventType="pull_request") */
Configure a dedicated secret to use for signature validation:
<?php /** * @GitHubWebHook(eventType="push", secret="push_secret") * @GitHubWebHook(eventType="pull_request", secret="pr_secret") */
You also can rely on a container parameter to configure the secret to use:
<?php /** * @GitHubWebHook(eventType="push", secret="%hook.push.secret%") */
Contributing
See CONTRIBUTING file.
Original Credits
- Sylvain MAUDUIT (@Swop) as main author.
License
This library is released under the MIT license. See the complete license in the bundled LICENSE file.