README

The olvlvl/delayed-event-dispatcher package provides an event dispatcher that delays event dispatching to a later time in the application life.

A delayed event dispatcher is useful to reduce the response time of your HTTP application when events can perfectly be dispatched after the response has been sent. For instance, updating an entity that would require clearing cache, performing projections, or reindexing, all of which have nothing to do with the response itself. Delayed events are dispatched when flushed, but you can choose another solution entirely, like sending them to consumers using RabbitMQ or Kafka.

Because you're probably using one event dispatcher for your application you don't want all events to be delayed, some of them have to be dispatched immediately for your application to run properly, that's why you can specify an arbiter to determine which events to delay and which not to.

Finally, because you want all delayed events to be dispatched when you flush them—even when an exception is thrown—you can provide an exception handler. It's up to you to decide what to do. You'll probably want to recover, log the exception, and continue with dispatching the other events.

Disclaimer: The delayed event dispatcher is a decorator that is meant to be used together with psr/event-dispatcher.

Instantiating a delayed event dispatcher

The delayed event dispatcher is a decorator, which means you'll need another event dispatcher to decorate.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$delayedEventDispatcher = new DelayedEventDispatcher($eventDispatcher);

Instantiating an inactive delayed event dispatcher

By default the delayed event dispatcher is active, which means it will delay events. This is fine for your HTTP application, but that's not something you want for the console or the consumer application. You can create a disabled delayed event dispatcher be defining the disabled option as true.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$disabledDelayedEventDispatcher = new DelayedEventDispatcher($eventDispatcher, true);

This is especially useful when your HTTP/console/consumer applications are deployed using the same artifact, that you can customize using environment variables.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$disabledDelayedEventDispatcher = new DelayedEventDispatcher(
    $eventDispatcher, 
    filter_var(getenv('MYAPP_DISABLE_DELAYED_EVENT_DISPATCHER'), FILTER_VALIDATE_BOOLEAN)
);

Flushing delayed events

Delayed events are flushed (dispatched) with the flush() method.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var DelayedEventDispatcher $delayedEventDispatcher */

$delayedEventDispatcher->dispatch($event1);
$delayedEventDispatcher->dispatch($event2);
$delayedEventDispatcher->flush();

Flushing delayed events with a custom flusher

By default, events are dispatched with the decorated event dispatcher when flushed, but you can choose another solution entirely, like sending them to consumers using RabbitMQ or Kafka.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var \PhpAmqpLib\Channel\AMQPChannel $channel */
/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$messagingDelayedEventDispatcher = new DelayedEventDispatcher(
    $eventDispatcher, 
    true,
    null,
    null,
    function (object $event) use ($channel) {
        $channel->basic_publish(json_encode($event), 'my_exchange', $event->getName());
    }
);

Deciding which events to delay and which not to

By default all events are delayed—if the delayed event dispatcher was created with disabled = false—but you can supply an arbiter to choose which events to delay and which not to. You can use the Delayable interface to mark your events, but it's not a requirement. The arbiter is a simple callable, its implementation is up to you.

<?php

use olvlvl\DelayedEventDispatcher\Delayable;
use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

$arbiter = function (object $event) {
    return $event instanceof Delayable;
};

/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$disabledDelayedEventDispatcher = new DelayedEventDispatcher($eventDispatcher, false, $arbiter);

Handling exceptions

By default exceptions thrown during the dispatching of events are not recovered, the dispatching halts, leaving delayed events in the queue. If you want to recover from these exceptions, and make sure all the events are dispatched, you'll want to provide and exception handler.

<?php

use olvlvl\DelayedEventDispatcher\DelayedEventDispatcher;

/* @var \Psr\Log\LoggerInterface $logger */

$exceptionHandler = function (\Throwable $error, object $event) use ($logger) {
    // The exception is recovered, we log it to fix it later
    $logger->danger($error);
};

/* @var \Psr\EventDispatcher\EventDispatcherInterface $eventDispatcher */

$disabledDelayedEventDispatcher = new DelayedEventDispatcher($eventDispatcher, false, null, $exceptionHandler);

Requirements

The package requires PHP 7.2 or later.

Installation

The recommended way to install this package is through Composer:

$ composer require olvlvl/delayed-event-dispatcher

Cloning the repository

The package is available on GitHub, its repository can be cloned with the following command line:

$ git clone https://github.com/olvlvl/delayed-event-dispatcher.git

Documentation

You can generate the documentation for the package and its dependencies with the make doc command. The documentation is generated in the build/docs directory. ApiGen is required. The directory can later be cleaned with the make clean command.

Testing

The test suite is ran with the make test command. PHPUnit and Composer need to be globally available to run the suite. The command installs dependencies as required. The make test-coverage command runs test suite and also creates an HTML coverage report in build/coverage. The directory can later be cleaned with the make clean command.

The package is continuously tested by Travis CI.

License

olvlvl/delayed-event-dispatcher is licensed under the New BSD License - See the LICENSE file for details.

olvlvl / delayed-event-dispatcher

Maintainers

Details