This package introduces a transactional layer to the Laravel Event Dispatcher. Its purpose is to ensure, without changing a single line of code, consistency between events dispatched during database transactions. This behavior is also applicable to Eloquent events (such as saved and created) by changing the configuration file.
Let's start with an example representing a simple process of ordering tickets. Assume that it involves database changes and a payment registration and that the custom event OrderWasProcessed is dispatched when the order is processed in the database.
DB::transaction(function() {
$user = User::find(...);
$concert = Concert::find(...);
$order = $concert->orderTickets($user, 3);
event(new OrderWasProcessed($order));
PaymentService::registerOrder($order);
});The transaction in the above example may fail for several reasons. For instance, an exception may occur in the orderTickets method or in the payment service. Also, it can fail simply due to a deadlock.
A failure will rollback database changes made during the transaction. However, this is not true for the OrderWasProcessed event, which is actually dispatched and eventually executed. Considering that this event may result in sending a confirmation e-mail to an user, managing it the right way becomes mandatory.
The purpose of this package is to ensure that events are actually dispatched if and only if the transaction in which they were dispatched succeeds. According to the example, this package guarantees that the OrderWasProcessed event is not dispatched if the transaction fails.
Please note that events dispatched out of transactions will bypass the transactional layer, meaning that it will be handled by the default Event Dispatcher. This is true also for events in which the $halt parameter is set to true.
The installation of this package in Laravel is automatic thanks to the Package Auto-Discovery feature of Laravel 5.5+.
Just add this package to the composer.json file and it will be ready for your application.
composer require fntneves/laravel-transactional-events
A configuration file is also part of this package. Run the following command to copy the provided configuration file transactional-events.php to your config folder.
php artisan vendor:publish --provider="Neves\Events\EventServiceProvider"
As Lumen is built on top of Laravel packages, this package should also work smoothly on this micro-web framework. Run the following command to install this package:
composer require fntneves/laravel-transactional-eventsIn order to configure the behavior of this package, copy the configuration files:
cp vendor/fntneves/laravel-transactional-events/src/config/transactional-events.php config/transactional-events.phpThen, in bootstrap/app.php, register the configuration and the service provider:
Note: This package must be registered after the default EventServiceProvider, so your event listeners are not overriden.
// The default EventServiceProvider must be registered.
$app->register(App\Providers\EventServiceProvider::class);
...
$app->configure('transactional-events');
$app->register(Neves\Events\EventServiceProvider::class);The transactional layer is enabled by default for the events placed under the App\Events namespace.
However, the easiest way to enable transactional behavior on your events is to implement the contract Neves\Events\Contracts\TransactionalEvent.
Note that events that implement it will behave as transactional events even when excluded in config.
namespace App\Events;
use Illuminate\Queue\SerializesModels;
use Illuminate\Foundation\Events\Dispatchable;
...
use Neves\Events\Contracts\TransactionalEvent;
class TicketsOrdered implements TransactionalEvent
{
use Dispatchable, InteractsWithSockets, SerializesModels;
...
}As this package does not require any changes in your code, you are still able to use the Event facade and call the event() or broadcast() helper to dispatch an event:
Event::dispatch(new App\Event\TicketsOrdered) // Using Event facade
event(new App\Event\TicketsOrdered) // Using event() helper method
broadcast(new App\Event\TicketsOrdered) // Using broadcast() helper methodEven if you are using queues, they will still work smothly because this package does not change the core behavior of the event dispatcher. They will be enqueued as soon as the active transaction succeeds. Otherwise, they will be discarded.
Reminder: Events are considered transactional when they are dispatched within transactions. When an event is dispatched out of transactions, they bypass the transactional layer.
The following keys are present in the configuration file:
The transactional behavior can be enabled or disabled by changing the following property:
'enable' => trueBy default, the transactional behavior will be applied to events on App\Events namespace. Feel free to use patterns and namespaces.
'transactional' => ['App\Events']Choose the events that should always bypass the transactional layer, i.e., should be handled by the default event dispatcher. By default, all *ed Eloquent events are excluded.
'excluded' => [
// 'eloquent.*',
'eloquent.booted',
'eloquent.retrieved',
'eloquent.created',
'eloquent.saved',
'eloquent.updated',
'eloquent.created',
'eloquent.deleted',
'eloquent.restored',
],Transactional events are not dispatched in tests.
This issue is fixed for Laravel 5.6.16+ (see #23832).
For previous versions, it is associated with the RefreshDatabase trait, namely when it uses database transactions to reset database after each test.
This package relies on events dispached when transactions begin/commit/rollback and as each is executed within a transaction that rollbacks when test finishes, the dispatched application events are never dispatcher. In order to get the expected behavior, use the Neves\Testing\RefreshDatabase trait in your tests instead of the one originally provided by Laravel.
This package is open-sourced software licensed under the MIT license.