acairns/radiate

Radiate event emitter

Radiate

, _(*1)

Introduction

Radiate is a package for managing Events., _(*2)

Basic Usage

Simply create an instance of the Emitter and emit events!, _(*3)

$emitter new Emitter($middleware);
$emitter->emit(new ExampleEvent);

Creating the Emitter

Radiate requires a pipeline of middleware when being created. The main middleware required to invoke listeners is an instance of the InvokeListenerMiddleware class., _(*4)

use Cairns\Radiate\Emitter;
use Cairns\Radiate\Inflector\HandleMethodInflector;
use Cairns\Radiate\Middleware\InvokeListenerMiddleware;

$invoker = new InvokeListenerMiddleware(
    $registry,
    $locator,
    $inflector
);

$emitter = new Cairns\Radiate\Emitter([
    $invoker
]);

In order to invoke a Listener, the middleware needs to know the available Listeners ($registry), how to create an instance of the subscribed Listeners ($locator) and how to determine which method should be invoked ($inflector)., _(*5)

Registrys

A Registry is a simple class responsible of keeping track all of the subscribed Listeners., _(*6)

Locators

The responsibility of the locator is to take a Fully Qualified Class Name for a Listener and to return an instance. If you are using a Dependency Injection container, then this is where you want to resolve the concrete instance., _(*7)

Inflectors

The job of the inflector is to determine which method should be called on a particular Listener given a specific Event. Several Inflectors are provided for common setups., _(*8)

HandleMethodInflector

The HandleMethodInflector ensures the handle() method is returned. A Listener could look like this:, _(*9)

final class DisableTransporters
{
    public function handle(WarpDriveEngaged $event)
    {
        // Do Something
    }
}

TypehintMethodInflector

The TypehintMethodInflector ensures any method dependent on the type of event is returned. A Listener could look like this:, _(*10)

final class DisableTransporters
{
    public function whenWarpDriveEngaged(WarpDriveEngaged $event)
    {
        // Do Something
    }

    public function whenShieldsWereRaised(ShieldsWereRaised $event)
    {
        // Do Something
    }
}

When using the TypehintMethodInflector, you can define multiple public methods so that the same Listener can respond to different events., _(*11)

Simple Example

final class WarpDriveEngaged
{
    private $speed;

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

    public function getSpeed()
    {
        return $this->speed;
    }
}

final class DisableTransporters
{
    public function whenWarpDriveIsEngaged(WarpDriveEngaged $event)
    {
        // safety first!
    }
}

$registry = new \Cairns\Radiate\Registry\TypehintedClassRegistry;
$registry->register(DisableTransporters::class);

$locator = new Cairns\Radiate\Locator\InMemoryListenerLocator;
$locator->add(new DisableTransporters);

$invoker = new \Cairns\Radiate\Middleware\InvokeListenerMiddleware(
    $registry,
    $locator,
    new Cairns\Radiate\Inflector\TypehintMethodInflector
);

$emitter = new Cairns\Radiate\Emitter([
    $invoker
]);

$emitter->emit(new WarpDriveEngaged(9));

Inspiration

This library is inspired by:, _(*12)

• SimpleBus/MessageBus
• thephpleague/tactician
• thephpleague/event

Contributing

Even though this is just an experiment for now, I'm totally open to ideas. Shoot over a PR!, _(*13)

If you decide to help out, here are some helpful things to check:, _(*14)

Running tests

$ ./vendor/bin/phpunit

Code Sniffer

$ ./vendor/bin/phpcs --standard=PSR2 ./src/

Todo

• [ ] Bump to >=PHP7, update codebase (return types, typehint, etc.)
• [ ] Extract examples into example directory
• [ ] Make registry serialisable, and constructable from a serialised registry