shooka/laravel-modelevents

Let a service provider handle your model events

v0.3.0 2016-09-22 18:25 UTC

Requires

• php: >=5.5.0
• laravel/framework: 5.1.*|5.2.*|5.3.*

Requires (Dev)

• orchestra/testbench: ^3.3
• phpunit/phpunit: ^5.5
• satooshi/php-coveralls: dev-master

MIT

• Nicolai Østby

• event
• events
• model
• laravel
• eloquent
• listeners
• observe
• listen

README

Have you ever wondered where to put your eloquent model events? It is now easier than ever to apply listeners to your models.

Installation

Add this package to your Laravel project by running:

composer require shooka/laravel-modelevents 0.3.*

To publish the necessary files, add the ServiceProvider to the array of providers in config/app.php:

Shooka\ModelEvents\ServiceProvider::class,

Next, publish the files by running:

php artisan vendor:publish --provider="Shooka\ModelEvents\ServiceProvider"

This publishes two files:

• A ModelEvents/UserEvent.php file that contains a dummy class that shows what future ModelEvents are supposed to look like.
• A Providers/ModelEventServiceProvider.php with an empty array of listeners that maps actual Eloquent model events to the ModelEvent classes.

As the new ModelEventServiceProvider has been published, you can add it to the array of providers:

App\Providers\ModelEventServiceProvider::class,

Don't forget to remove the original one from the array:

Shooka\ModelEvents\ServiceProvider::class,

Usage

This package is making use of some of the great features of Laravel which means that it is very easy to use in both new and existing Laravel projects.

The events that are supported out of the box are the standard Laravel model events: creating, created, updating, updated, saving, saved, deleting, deleted, restoring, and restored

Custom events

If you want to define any custom events, they should be added to the $observables array:

class Product extends Model
{
    protected $observables = [
        'sold',
        'shipped',
        'returned',
        ...
    ];
}

Those events are now observable in the ModelEvent:

class ProductEvent extends ModelEvent
{
    public function returned($product) {
        // Increase stock count
    }
}

Activating a listener

To add a listener to an eloquent model, just map the model to a ModelEvent in the ModelEventServiceProvider:

protected $listeners = [
    \App\Product::class => \App\ModelEvents\ProductEvent::class,
];

The ModelEvent could be placed anywhere, but is in this example put in the ModelEvents folder published by the command from the Installation chapter.