2017 © Pedro Peláez
 

library laravel-transactional-events

Transactional layer for Laravel Event Dispatcher

image

fntneves/laravel-transactional-events

Transactional layer for Laravel Event Dispatcher

  • Friday, June 1, 2018
  • by fntneves
  • Repository
  • 4 Watchers
  • 36 Stars
  • 5,819 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 8 Forks
  • 0 Open issues
  • 17 Versions
  • 82 % Grown

The README.md

Transaction-aware Event Dispatcher for Laravel

Latest Stable Version Total Downloads, (*1)

This Laravel package introduces Transaction-aware Event Dispatcher.
It ensures the events dispatched within a database transaction are dispatched only if the outer transaction successfully commits. Otherwise, the events are discarded and never dispatched., (*2)

Note: Laravel 8.17 introduced a new method DB::afterCommit that allows one to achieve the same of this package. Yet, it lacks transaction-aware behavior support for Eloquent events., (*3)

Table of Contents

Motivation

Consider the following example of ordering tickets that involves changes to the database.br/ The orderTickets dispatches the custom OrderCreated event. In turn, its listener sends an email to the user with the order details., (*4)

DB::transaction(function() {
    ...
    $order = $concert->orderTickets($user, 3); // internally dispatches 'OrderCreated' event
    PaymentService::registerOrder($order);
});

In the case of transaction failure, due to an exception in the orderTickets method or even a deadlock, the database changes are completely discarded., (*5)

Unfortunately, this is not true for the already dispatched OrderCreated event. This results in sending the order confirmation email to the user, even after the order failure., (*6)

The purpose of this package is thus to hold events dispatched within a database transaction until it successfully commits. In the above example the OrderCreated event would never be dispatched in the case of transaction failure., (*7)

Installation

Laravel Package Notes
5.8.x-7.x 1.8.x
8.x-11.x 2.x >2.1.x requires PHP 8+

Laravel

  • Install this package via composer:
composer require fntneves/laravel-transactional-events
  • Publish the provided transactional-events.php configuration file:
php artisan vendor:publish --provider="Neves\Events\EventServiceProvider"

Lumen

  • Install this package via composer:

``` bash composer require fntneves/laravel-transactional-events, (*8)


- Manually copy the provided `transactional-events.php` configuration file to the `config` folder:

```bash
cp vendor/fntneves/laravel-transactional-events/src/config/transactional-events.php config/transactional-events.php
  • Register the configuration file and the service provider in bootstrap/app.php:br/ 
// Ensure the original EventServiceProvider is registered first, otherwise your event listeners are overriden.
$app->register(App\Providers\EventServiceProvider::class);

$app->configure('transactional-events');
$app->register(Neves\Events\EventServiceProvider::class);

Usage

The transaction-aware layer is enabled out of the box for the events under the App\Events namespace., (*9)

This package offers three distinct ways to dispatch transaction-aware events: - Implement the Neves\Events\Contracts\TransactionalEvent contract; - Use the generic TransactionalClosureEvent event; - Use the Neves\Events\transactional helper; - Change the configuration file., (*10)

Use the contract, Luke:

The simplest way to mark events as transaction-aware events is implementing the Neves\Events\Contracts\TransactionalEvent contract:br/, (*11)

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;

    ...
}

And that's it. There are no further changes required., (*12)

What about Jobs?

This package provides a generic TransactionalClosureEvent event for bringing the transaction-aware behavior to custom behavior without requiring specific events., (*13)

One relevant use case is to ensure that Jobs are dispatched only after the transaction successfully commits:, (*14)

DB::transaction(function () {
    ...
    Event::dispatch(new TransactionalClosureEvent(function () {
        // Job will be dispatched only if the transaction commits.
        ProcessOrderShippingJob::dispatch($order);
    });
    ...
});

And that's it. There are no further changes required., (*15)

Configuration

The configuration file includes the following parameters:, (*16)

Enable or disable the transaction-aware behavior:, (*17)

'enable' => true

By default, the transaction-aware behavior will be applied to all events under the App\Events namespace. br/Feel free to use patterns and namespaces., (*18)

'transactional' => [
    'App\Events'
]

Choose the events that should always bypass the transaction-aware layer, i.e., should be handled by the original event dispatcher. By default, all *ed Eloquent events are excluded. The main reason for this default value is to avoid interference with your already existing event listeners for Eloquent events., (*19)

'excluded' => [
    // 'eloquent.*',
    'eloquent.booted',
    'eloquent.retrieved',
    'eloquent.saved',
    'eloquent.updated',
    'eloquent.created',
    'eloquent.deleted',
    'eloquent.restored',
],

Frequently Asked Questions

Can I use it for Jobs?

Yes. As mentioned in Usage, you can use the generic TransactionalClosureEvent(Closure $callable) event to trigger jobs only after the transaction commits., (*20)

License

This package is open-sourced software licensed under the MIT license., (*21)

The Versions

01/06 2018

dev-master

9999999-dev

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves

01/06 2018

1.4.4

1.4.4.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves

21/04 2018

1.4.3

1.4.3.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

by Francisco Neves

14/04 2018

1.4.2

1.4.2.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

by Francisco Neves

01/04 2018

1.4.1

1.4.1.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

by Francisco Neves

31/03 2018

1.4.0

1.4.0.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

by Francisco Neves

07/02 2018

1.3.2

1.3.2.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

by Francisco Neves

03/02 2018

1.3.1

1.3.1.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

21/01 2018

1.3.0

1.3.0.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

21/01 2018

dev-fn-switch_transactional_model_events

dev-fn-switch_transactional_model_events

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

12/01 2018

1.2.0

1.2.0.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

27/12 2017

1.1.1

1.1.1.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

10/10 2017

1.1.0

1.1.0.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Development Requires

by Francisco Neves

08/09 2017

dev-develop

dev-develop

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves

06/09 2017

1.0.2

1.0.2.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves

06/09 2017

1.0.1

1.0.1.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves

06/09 2017

1.0.0

1.0.0.0

Transactional layer for Laravel Event Dispatcher

  Sources   Download

MIT

The Requires

 

The Development Requires

by Francisco Neves