Skip to content

Latest commit

 

History

History
223 lines (171 loc) · 8.6 KB

under-the-hood.md

File metadata and controls

223 lines (171 loc) · 8.6 KB
Raw

Table of Contents | Getting Started | Customisation | How To | Examples | Under The Hood | Contributing

Under The Hood

Commands

Yay! is shipped with a collection of commands that are necessary to configure and control a running Yay! installation.

Command Description Example
yay:integration:enable <name> <path> Enables an integration. php bin/console --env=prod yay:integration:enable demo integration/demo
yay:integration:disable <name> Disables an integration. php bin/console --env=prod yay:integration:disable demo
yay:integration:validate <name> <path> Validates an integration. php bin/console --env=prod yay:integration:validate demo integration/demo
yay:recalculate <player> Recalculates a player's progress. php bin/console --env=prod yay:recalculate alex.doe
Hint: It is important to always pass the environment Yay! is running in as the env parameter.

Events

Yay! provides a set of events to easily hook into. How to work with events is illustrated through the ActivityListener and the services.yml configuration.

# services.yml
MyListener:
    tags:
        - { name: yay.event_listener, event: yay.engine.grant_personal_action, method: onGrantPersonalAction }
# MyListener.php
class MyListener
{
    public function onGrantPersonalAction(ObjectEvent $event): void
    {
     /** @var PersonalAction $personalAction */
     $personalAction = $event->getObject();

     // ...
    }
}
Name Type Object Description
yay.engine.pre_save ObjectEvent Entity* Triggered before an entity is saved.
yay.engine.post_save ObjectEvent Entity* Triggered after an entity was saved.
yay.engine.grant_personal_achievement ObjectEvent PersonalAchievement Triggered after a player has been awarded with a new achievement.
yay.engine.grant_personal_action ObjectEvent PersonalAction Triggered after a player has been accounted a new action.
yay.engine.create_player ObjectEvent Player Triggered after a new player has been created.
yay.engine.change_level ObjectEvent Player Triggered after a player's level has been changed.
yay.engine.change_score ObjectEvent Player Triggered after a player's score has been changed.

Webhooks

Webhooks are the link that joins the outside world with your Yay! instance.

Internals

Processors implement the ProcessorInterface(1, 2) for incoming and outgoing webhooks.

Incoming processors

During execution of the webhook the process method of the processor is called. A Request instance is passed, it contains all request data passed to the application.

The webhook implementation requires that after the processor or all processors via the chain processor are run the request object holds both username and action attributes.

Processors can be combined through chaining to maximise flexibility, you can follow the GitHub example to see all the benefits of processing webhook payloads. E.g you can process a payload from GitHub and then use a custom processor to map github usernames to internal usernames.

Processors are then available as part of a webhook route /webhook/incoming/{processor}/ and reachable via GET and POST.

// ProcessorInterface.php
namespace Component\Webhook\Incoming;
use Symfony\Component\HttpFoundation\Request;

interface ProcessorInterface
{
    public function getName(): string;

    public function process(Request $request): void;
}

// MyProcesor.php
use Component\Webhook\Incoming\ProcessorInterface
use Symfony\Component\HttpFoundation\Request;

class MyProcessor implements ProcessorInterface
{
    /* @var string */
    protected $name;

    public function __construct(string $name)
    {
     $this->name = $name;
    }

    public function getName(): string
    {
     return $this->name:
    }

    public function process(Request $request): void
    {
     // extract, transform data from $request object, assign $username and $action
     // $username = ...
     // $action = ...

     $request->request->set('username', $username);
     $request->request->set('action', $action);
    }
}

Built-in incoming processors

ChainProcessor

The ChainProcessor is able to chain multiple processors to maximise flexibility. It is configured in your integration configuration.

integration:
    webhooks:
     incoming_processors:
            # Chains multiple processors into one
            example-chain:
                type: chain
                arguments:
                    - [example-mycompany-jenkinsci, example-mycompany-users]
            # Your company provides a processor to transform Jenkins CI payloads
            example-mycompany-jenkinsci:
                type: class
                class: MyCompany\Component\Webhook\Incoming\Processor\JenkinsProcessor
            # Your company provides a second processor to map jenkins users to Yay! players
            # based on a static configuration file deployed with the application
            example-mycompany-users:
                type: class
                class: MyCompany\Component\Webhook\Incoming\Processor\StaticUserProcessor
                arguments: [ '%kernel.root_dir/../integration/mycompany/users.yml%' ]

URL: /webhook/incoming/example-chain/.

DummyProcessor

The DummyProcessor is able to push key, value pairs to the request object, useful for fallback or default configuration.

integration:
    webhooks:
     incoming_processors:
        example-dummy:
            type: dummy
            arguments:
                -
                    username: alex.doe
                    action: example.action

URL: /webhook/incoming/example-dummy/.

NullProcessor

The NullProcessor does nothing. Its process method is empty. It is used for testing.

integration:
    webhooks:
        incoming_processors:
            example-null:
                type: 'null'

URL: /webhook/incoming/example-null/.

StaticMapProcessor

The StaticMapProcessor remaps the specified request attribute values.

integration:
    webhooks:
     incoming_processors:
            example-static-map:
                type: static-map
                arguments:
                    - username
                    -
                    # username=octocate => username=alex.doe
                    octocat: alex.doe

URL: /webhook/incoming/example-static-map/.

SimpleProcessor

The SimpleProcessor accepts a json payload and extracts username and action fields.

{
	"username": "Alex Doe",
	"action": "example.action"
}
integration:
    webhooks:
     incoming_processors:
            example-simple:
                type: simple

URL: /webhook/incoming/example-simple/.

Third party incoming processors

Yay ships with a colleciton of incoming processors to connect to third parties like GitHub, GitLab, BitBucket, Travsic CI and more. Supported actions and events can be found at How to connect Third Parties.