README

Add transactional events to your eloquent models. Will automatically detect changes in your models within a transaction and will fire events on commit or rollback. Should mimic the same functionality as transactional callbacks in Ruby on Rails.

You want to use this if you want to listen on events fired by models within a transaction and you want to be sure the transaction has completed successfully (or is rolled back).

Installation

You can install the package via composer:

composer require mvanduijker/laravel-transactional-model-events

Usage

Just add the trait TransactionalAwareEvents to your model or base model.

<?php

class MyModel extends Model
{
    use TransactionalAwareEvents;
}

The following events will become available:

• afterCommit.created
• afterCommit.saved
• afterCommit.updated
• afterCommit.deleted
• afterCommit.restored
• afterCommit.forceDeleted
• afterRollback.created
• afterRollback.saved
• afterRollback.updated
• afterRollback.deleted
• afterRollback.restored
• afterRollback.forceDeleted

You can add listeners in you EventServiceProvider the same way as normal events

<?php

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'eloquent.afterCommit.created: App\Models\Shipment' => [
        'App\Listeners\SendShipmentNotification',
    ],
];

Or you can put them in your model boot method:

<?php

class PictureFile extends Model
{
    use TransactionalAwareEvents;
    
    public static function boot()
    {
        parent::boot();
        
        static::registerModelEvent('afterCommit.deleted', function ($model) {
            if (Storage::exists($model->file)) {
                Storage::delete($model->file);            
            }
        });
    }
}

You should also be able to map them to event classes

<?php

class PictureFile extends Model
{
    use TransactionalAwareEvents;
    
    protected $dispatchesEvents = [
        'afterCommit.created' => PictureFileCreated::class,
        'afterCommit.deleted' => PictureFileDeleted::class,
    ];
}

And as icing on the cake, you can observe them with the following methods:

• afterCommitCreated
• afterCommitSaved
• afterCommitUpdated
• afterCommitDeleted
• afterCommitRestored
• afterCommitForceDeleted
• afterRollbackCreated
• afterRollbackSaved
• afterRollbackUpdated
• afterRollbackDeleted
• afterRollbackRestored
• afterRollbackForceDeleted

For example:

<?php

class PictureFileObserver
{
    public function afterCommitDeleted(PictureFile $model)
    {
        if (Storage::exists($model->file)) {
            Storage::delete($model->file);            
        }
    }
}

And register the observer in you ServiceProvider:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        PictureFile::observe(PictureFileObserver::class);
    }
}

Since Laravel version 10.44 it's also possible to register the observer with theObservedBy attribute.

<?php

use Illuminate\Database\Eloquent\Attributes\ObservedBy; 

#[ObservedBy(PictureFileObserver::class)]
class PictureFileObserver
{
...
}

Multiple database connections are supported, events are triggered when the transaction is committed on the configured connection of the model.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Mark van Duijker
• All Contributors

License

The MIT License (MIT). Please see License File for more information.