thecodingmachine/gitlab-hook-middleware

A PSR-15 middleware to manage Gitlab hooks.

v1.0.1 2019-09-10 10:00 UTC

Requires

• php: >=7.1
• psr/container: ^1
• psr/http-message: ^1
• psr/http-server-handler: ^1
• psr/http-server-middleware: ^1
• psr/log: ^1
• thecodingmachine/funky: ^1
• zendframework/zend-diactoros: ^1.8.5

Requires (Dev)

• maglnet/composer-require-checker: ^1.0
• mnapoli/simplex: ^0.5
• php-coveralls/php-coveralls: ^2
• phpstan/phpstan: ^0.10.3
• phpunit/phpunit: ^7.3.1
• squizlabs/php_codesniffer: ^3.3.1
• thecodingmachine/discovery: ^1
• thecodingmachine/phpstan-strict-rules: ^0.10.3

MIT

• Marc Teyssier
• David Négrier

• middleware
• HOOK
• gitlab

README

Gitlab hook PSR-15 middleware

This package is a PSR-15 Middleware to receive events sent by a Gitlab webhook and send them to a listener.

It's possible to use directly the hookReceiver to build the event object, but you could check the Gitlab authentification.

How does it work

The middleware checks the header named X-GITLAB-TOKEN and builds an event object. The object is dispatched to a listener that you must implement.

The middleware takes care of unserializing the payload and provides you with nice PHP objects instead of raw JSON data. It's possible to get the initial array payload with the getPayload() function.

Your listener will receive all events. If you want to listen on a specific event type, you must check the object type.

Event List:

Scope	Hook	Header	Object
Project	Push Hook	Push Hook	TheCodingMachine\GitlabHook\Model\Push
Project	Tag Push Hook	Tag Push Hook	TheCodingMachine\GitlabHook\Model\TagPush
Project	Note Hook	Note Hook	Not implemented
Project	Pipeline Hook	Pipeline Hook	TheCodingMachine\GitlabHook\Model\Pipeline
Project	Build Hook	Build Hook	TheCodingMachine\GitlabHook\Model\Build
Group	Project created	System Hook	TheCodingMachine\GitlabHook\Model\ProjectCreate
Group	Project destroyed	System Hook	TheCodingMachine\GitlabHook\Model\ProjectDestroy
Group	Project renamed	System Hook	TheCodingMachine\GitlabHook\Model\ProjectRename
Group	Project transferred	System Hook	TheCodingMachine\GitlabHook\Model\ProjectTrasnfer
Group	New Team Member	System Hook	TheCodingMachine\GitlabHook\Model\TeamMemberAdd
Group	Team Member Removed	System Hook	TheCodingMachine\GitlabHook\Model\TeamMemberRemove
Group	User created	System Hook	TheCodingMachine\GitlabHook\Model\UserCreate
Group	User removed	System Hook	TheCodingMachine\GitlabHook\Model\UserDestroy
Group	User failed login	System Hook	TheCodingMachine\GitlabHook\Model\UserFailedLogin
Group	User renamed	System Hook	TheCodingMachine\GitlabHook\Model\UserRename
Group	Key added	System Hook	TheCodingMachine\GitlabHook\Model\KeyCreate
Group	Key removed	System Hook	TheCodingMachine\GitlabHook\Model\KeyDestroy
Group	Group created	System Hook	TheCodingMachine\GitlabHook\Model\GroupCreate
Group	Group removed	System Hook	TheCodingMachine\GitlabHook\Model\GroupDestroy
Group	Group renamed	System Hook	TheCodingMachine\GitlabHook\Model\GroupRename
Group	New Group Member	System Hook	TheCodingMachine\GitlabHook\Model\UserGroupAdd
Group	Group Member Removed	System Hook	TheCodingMachine\GitlabHook\Model\UserGroupRemove
Group	Push events	System Hook	TheCodingMachine\GitlabHook\Model\Push
Group	Tag events	System Hook	TheCodingMachine\GitlabHook\Model\Tag
Group	Merge request events	System Hook	TheCodingMachine\GitlabHook\Model\MergeRequest
Group	Repository Update events	System Hook	TheCodingMachine\GitlabHook\Model\RepositoryUpdate

Example

Listener implementation

<?php
namespace Test;

class Listener implements HookListenerInterface {
    /**
     * @param \TheCodingMachine\GitlabHook\EventInterface $event
     */
     public function onEvent(EventInterface $event) {
         // Compute Push event
         if($event instanceof TheCodingMachine\GitlabHook\Model\Push::class) {
             // Display before
             echo $event->getBefore();
             // Display the project name
             echo $event->getProject()->getName();
         }
         // Compute MergeRequest event
         if($event instanceof TheCodingMachine\GitlabHook\Model\MergeRequest::class) {
             // Display target branch (this is in object_attributes)
             echo $event->getTargetBranch();
             // Get initial payload
             var_dump($event->getPayload());
         }
     }
}
?>

Use without middleware

// Create your listener
$listener = new Test\Listerner();

// Register your listener in the main HookReceiver instance
$hookReceiver = new TheCodingMachine\GitlabHook\HookReceiver([$listener]);

// Call handler function to execute check
// $payload is array (json_decode) of data send by Gitlab webhook
// $header is the result of HTTP_X_GITLAB_TOKEN header 
$hookReceiver->handle($payload, $header);

Use a middleware

// Create your listener
$listener = new Test\Listerner();

// Register your listener in the main HookReceiver instance
$hookReceiver = new TheCodingMachine\GitlabHook\HookReceiver([$listener]);

// Create a PSR-3 logger
$logger = new Psr\Log\NullLogger(); 

// Inject hookReceiver in Gitlab middleware
// You must inject this middleware in the middleware pipe of your favorite framework.
// See your framework documentation on how to do that.
$middleware = new TheCodingMachine\GitlabHook\GitlabHookMiddleware($hookReceiver, 'secret', $logger);