olvlvl / delayed-event-dispatcher
Delays the dispatching of events
Installs: 4 204
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 1
Requires
- php: >=7.2
- psr/event-dispatcher: ^1.0
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.