README

This module provides a PSR-14 event dispatcher to Silverstripe CMS applications. It is useful for reactive programming paradigms in lieu of traditional imperative designs through hooks like onAfterWrite.

Most of the underlying work is handled by Symfony's EventDispatcher, but this can be replaced with through dependency injection.

Requirements

silverstripe/framework: ^4.5

Installation

$ composer require silverstripe/event-dispatcher

Usage

There are three main components to the API:

The Dispatcher is responsible for registering event listeners and triggering events
Listeners are classes that trigger events, typically via extension hooks
Handlers are classes that execute code in response to an event.

Dispatching an event

use SilverStripe\EventDispatcher\Dispatch\Dispatcher;
use SilverStripe\EventDispatcher\Symfony\Event;

Dispatcher::singleton()->trigger('createOrder', Event::create(
    null,
    [
        'id' => $order->ID,
        'paymentMethod' => $order->PaymentMethod
    ]
));

The trigger function takes two arguments: string $eventName and EventContextInterface $context. The $context object can pass arbitrary data to any handlers that are subscribed to the event.

Event handling

Event handlers must implement EventHandlerInterface, which requires a fire() method.

use SilverStripe\EventDispatcher\Dispatch\EventHandlerInterface;
use SilverStripe\EventDispatcher\Event\EventContextInterface;

class OrderHandler implements EventHandlerInterface
{
    public function fire(EventContextInterface $context): void
    {
        $orderID = $context->get('id');
        $paymentMethod = $context->get('paymentMethod');
        // Do something in response to the order being created
    }
}

Subscribing to events

The best way to register your event handlers with the dispatcher is through config.

SilverStripe\Core\Injector\Injector:
  SilverStripe\EventDispatcher\Dispatch\Dispatcher:
    properties:
      handlers:
        # Arbitrary key. Allows other config to override.
        orders:
          on: [ orderCreated ]
          handler: %$MyProject\MyOrderHandler

Unsubscribing to events

To remove an event handler, override the config with an off node.

SilverStripe\Core\Injector\Injector:
  SilverStripe\EventDispatcher\Dispatch\Dispatcher:
    properties:
      handlers:
        orders:
          off: [ orderCreated ]

Managing events procedurally

To interact with the Dispatcher instance directly, use a DispatcherLoaderInterface.

use SilverStripe\EventDispatcher\Dispatch\DispatcherLoaderInterface;
use SilverStripe\EventDispatcher\Dispatch\EventDispatcherInterface;

class MyLoader implements DispatcherLoaderInterface
{
    public function addToDispatcher(EventDispatcherInterface $dispatcher) : void
    {
        $dispatcher->addListener('myEvent', $myHandler);
        $dispatcher->removeListener('anotherEvent', $anotherHandler);
    }
}

Then, register the loader in Injector.

SilverStripe\Core\Injector\Injector:
  SilverStripe\EventDispatcher\Dispatch\Dispatcher:
    properties:
      loaders:
        myLoader: %$MyProject\MyLoader

Action identifiers and context

Each of these handlers is passed a context object that exposes an action identifier. This is a string that provides specific information about what happened in the event that the handler can then use in its implementation. For instance, if you want to write event handlers for form submissions, where some handlers are for all form submissions, while others are for specific forms, you might pass the name of the form as an action identifier in your EventContext object.

use SilverStripe\EventDispatcher\Dispatch\Dispatcher;
use SilverStripe\EventDispatcher\Symfony\Event;

Dispatcher::singleton()->trigger('formSubmitted', Event::create(
    'contact',
    [
        'name' => $formData['Name'],
        // etc..
    ]
));

Events are always called with eventName.<action identifier>. For instance formSubmitted.contact, allowing the subscribers to only react to a specific subset of events.

SilverStripe\Core\Injector\Injector:
  SilverStripe\EventDispatcher\Dispatch\Dispatcher:
    properties:
      handlers:
        forms:
          # handler for all form submissions
          on: [ formSubmitted ]
          handler: %$MyProject\MyFormHandler
        contactForm:
          # handler for all a specific form
          on: [ formSubmitted.contact ]
          handler: %$MyProject\MyContactHandler

In this case, a contact form submission results in two handlers firing, in order of specificity (formSubmitted.contact first).

How to find your action identifier

The easiest way to debug events is to put breakpoints or logging into the Dispatcher::trigger() function. This will provide all the detail you need about what events are triggered when, and with what context.

public function trigger(string $event, EventContextInterface $context): void
{
    error_log($event);
    error_log($context->getAction());
    // ...

When the logging is in place you just go to the CMS and perform the action you are interested in. This should narrow the list of identifier down to a much smaller subset.

Event context

In the above example, the contact form data is passed to the Event object as context.

use SilverStripe\EventDispatcher\Dispatch\Dispatcher;
use SilverStripe\EventDispatcher\Symfony\Event;

Dispatcher::singleton()->trigger('formSubmitted', Event::create(
    'contact',
    [
        'name' => $formData['Name'],
        // etc..
    ]
));

In a handler, this can be accessed using the get(string $property) method.

public function fire(EventContextInterface $context): void
{
    $name = $context->get('Name');
    // do more stuff...
}

Note that get fails gracefully, and will return null when a property doesn't exist.

License

See License

Bugtracker

Bugs are tracked in the issues section of this repository. Before submitting an issue please read over existing issues to ensure yours is unique.

If the issue does look like a new bug:

Create a new issue
Describe the steps required to reproduce your issue, and the expected outcome. Unit tests, screenshots and screencasts can help here.
Describe your environment as detailed as possible: Silverstripe version, Browser, PHP version, Operating System, any installed Silverstripe modules.

Please report security issues to the module maintainers directly. Please don't file security issues in the bugtracker.

Development and contribution

If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.

silverstripe / event-dispatcher

Maintainers

Details