genealabs/laravel-pivot-events

This package introduces new eloquent events for sync(), attach(), detach() or updateExistingPivot() methods on BelongsToMany relation.

11.0.0 2024-03-14 23:24 UTC

Requires

• illuminate/database: ^8.0|^9.0|^10.0|^11.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^9.0
• phpunit/phpunit: ^10.5
• symfony/thanks: ^1.0

MIT

• Mike Bronner

• laravel pivot events
• laravel BelongsToMany events
• eloquent extra events
• laravel sync events
• eloquent events

README

This package introduces new eloquent events for sync(), attach(), detach(), or updateExistingPivot() methods on BelongsToMany and MorphToMany relationships.

This package is a fork of fico7489/laravel-pivot created mainly to address compatibility issues with Laravel Telescope and Model Caching for Laravel.

Sponsors

We thank the following sponsors for their generosity. Please take a moment to check them out:

• LIX

Requirements

• Laravel 8.0+
• PHP 7.3+

Installation

1.Install package with composer: composer require "genealabs/laravel-pivot-events:*"

1. Use GeneaLabs\LaravelPivotEvents\Traits\PivotEventTrait trait in your base model or only in particular models.

   // ...
   use GeneaLabs\LaravelPivotEvents\Traits\PivotEventTrait;
   use Illuminate\Database\Eloquent\Model;
   
   abstract class BaseModel extends Model
   {
       use PivotEventTrait;
       // ...
   }

New Eloquent Events

You can check all eloquent events here: https://laravel.com/docs/5.8/eloquent#events)

New events are :

• pivotSyncing, pivotSynced
• pivotAttaching, pivotAttached
• pivotDetaching, pivotDetached
• pivotUpdating, pivotUpdated

The easiest way to catch events is using methods in your model's boot() method:

public static function boot()
{
    parent::boot();

    static::pivotSyncing(function ($model, $relationName) {
        //
    });
     
    static::pivotSynced(function ($model, $relationName, $changes) {
        //
    });

    static::pivotAttaching(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        //
    });
    
    static::pivotAttached(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        //
    });
    
    static::pivotDetaching(function ($model, $relationName, $pivotIds) {
        //
    });

    static::pivotDetached(function ($model, $relationName, $pivotIds) {
        //
    });
    
    static::pivotUpdating(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        //
    });
    
    static::pivotUpdated(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        //
    });
    
    static::updating(function ($model) {
        //this is how we catch standard eloquent events
    });
}

You can also catch them using dedicated Event Listeners:

\Event::listen('eloquent.*', function ($eventName, array $data) {
    echo $eventName;  //e.g. 'eloquent.pivotAttached'
});

Supported Relationships

BelongsToMany and MorphToMany

Which events are dispatched and when they are dispatched

Four BelongsToMany methods dispatches events from this package :

attach()
Dispatches one pivotAttaching and one pivotAttached event.
Even when more rows are added only one event is dispatched for all rows but in that case, you can see all changed row ids in the $pivotIds variable, and the changed row ids with attributes in the $pivotIdsAttributes variable.

detach()
Dispatches one pivotDetaching and one pivotDetached event.
Even when more rows are deleted only one event is dispatched for all rows but in that case, you can see all changed row ids in the $pivotIds variable.

updateExistingPivot()
Dispatches one pivotUpdating and one pivotUpdated event.
You can change only one row in the pivot table with updateExistingPivot.

sync()
Dispatches one pivotSyncing and one pivotSynced event.
Whether a row was attached/detached/updated during sync only one event is dispatched for all rows but in that case, you can see all the attached/detached/updated rows in the $changes variables.
E.g. How does sync work: The sync first detaches all associations and then attaches or updates new entries one by one.

Usage

We have three tables in database users(id, name), roles(id, name), role_user(user_id, role_id). We have two models :

class User extends Model
{
    use PivotEventTrait;
    // ...

    public function roles()
    {
        return $this->belongsToMany(Role::class);
    }

    static::pivotSynced(function ($model, $relationName, $changes) {
        echo 'pivotSynced';
        echo get_class($model);
        echo $relationName;
        print_r($changes);
    });    

    static::pivotAttached(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        echo 'pivotAttached';
        echo get_class($model);
        echo $relationName;
        print_r($pivotIds);
        print_r($pivotIdsAttributes);
    });
    
    static::pivotUpdated(function ($model, $relationName, $pivotIds, $pivotIdsAttributes) {
        echo 'pivotUpdated';
        echo get_class($model);
        echo $relationName;
        print_r($pivotIds);
        print_r($pivotIdsAttributes);
    });

    static::pivotDetached(function ($model, $relationName, $pivotIds) {
        echo 'pivotDetached';
        echo get_class($model);
        echo $relationName;
        print_r($pivotIds);
    });

    // ...
}

class Role extends Model
{
    // ...
}

Attaching

For attach() or detach() one event is dispatched for both pivot ids.

Attaching With Primary Key

Running this code

$user = User::first();
$user->roles()->attach(1);

You will see this output

pivotAttached
App\Models\User
roles
[1]
[1 => []]

Attaching with array

Running this code

$user = User::first();
$user->roles()->attach([1]);

You will see this output

pivotAttached
App\Models\User
roles
[1]
[1 => []]

Attaching with model

Running this code

$user = User::first();
$user->roles()->attach(Role::first());

You will see this output

pivotAttached
App\Models\User
roles
[1]
[1 => []]

Attaching with collection

Running this code

$user = User::first();
$user->roles()->attach(Role::get());

You will see this output

pivotAttached
App\Models\User
roles
[1, 2]
[1 => [], 2 => []]

Attaching with array (id => attributes)

Running this code

$user = User::first();
$user->roles()->attach([1, 2 => ['attribute' => 'test']], ['attribute2' => 'test2']);

You will see this output

pivotAttached
App\Models\User
roles
[1, 2]
[1 => [], 2 => ['attribute' => 'test', 'attribute2' => 'test2']]

Syncing

Running this code

$user = User::first();
$user->roles()->attach([
     1 => ['pivot_attribut' => 1],
     2 => ['pivot_attribut' => 0]
 ]);
 $user->roles()->sync([
     1 => ['pivot_attribut' => 0]
     3 => ['pivot_attribut' => 1]
 ]);

You will see this output

pivotSynced
App\Models\User
roles
[
   "attached" => [
     0 => 3
   ]
   "detached" => [
     1 => 2
   ]
   "updated" => [
     0 => 1
   ]
 ]

Detaching

Running this code

$user = User::first();
$user->roles()->detach([1, 2]);

You will see this output

pivotAttached
App\Models\User
roles
[1, 2]

Updating

Running this code

$user = User::first();
$user->roles()->updateExistingPivot(1, ['attribute' => 'test']);

You will see this output

pivotUpdated
App\Models\User
roles
[1]
[1 => ['attribute' => 'test']]