4 events for adding and removing roles or permissions (#2742)

* Added Events `PermissionAttached`, `PermissionDetached`, `RoleAttached` and `RoleDetached`

---------

Co-authored-by: Sven Wegner <[email protected]>
Co-authored-by: Chris Brown <[email protected]>

Author: 3 people

config/permission.php

@@ -110,6 +110,17 @@
      */
     'register_octane_reset_listener' => false,
 
+    /*
+     * Events will fire when a role or permission is assigned/unassigned:
+     * \Spatie\Permission\Events\RoleAttached
+     * \Spatie\Permission\Events\RoleDetached
+     * \Spatie\Permission\Events\PermissionAttached
+     * \Spatie\Permission\Events\PermissionDetached
+     *
+     * To enable, set to true, and then create listeners to watch these events.
+     */
+    'events_enabled' => false,
+
     /*
      * Teams Feature.
      * When set to true the package implements teams using the 'team_foreign_key'.

src/Events/PermissionAttached.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spatie\Permission\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Collection;
+use Spatie\Permission\Contracts\Permission;
+
+class PermissionAttached
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Internally the HasPermissions trait passes an array of permission ids (eg: int's or uuid's)
+     * Theoretically one could register the event to other places and pass an Eloquent record.
+     * So a Listener should inspect the type of $permissionsOrIds received before using.
+     *
+     * @param  array|int[]|string[]|Permission|Permission[]|Collection  $permissionsOrIds
+     */
+    public function __construct(public Model $model, public mixed $permissionsOrIds) {}
+}

src/Events/PermissionDetached.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spatie\Permission\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Collection;
+use Spatie\Permission\Contracts\Permission;
+
+class PermissionDetached
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Internally the HasPermissions trait passes $permissionsOrIds as an Eloquent record.
+     * Theoretically one could register the event to other places and pass an array etc.
+     * So a Listener should inspect the type of $permissionsOrIds received before using.
+     *
+     * @param  array|int[]|string[]|Permission|Permission[]|Collection  $permissionsOrIds
+     */
+    public function __construct(public Model $model, public mixed $permissionsOrIds) {}
+}

src/Events/RoleAttached.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spatie\Permission\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Collection;
+use Spatie\Permission\Contracts\Role;
+
+class RoleAttached
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Internally the HasRoles trait passes an array of role ids (eg: int's or uuid's)
+     * Theoretically one could register the event to other places passing other types
+     * So a Listener should inspect the type of $rolesOrIds received before using.
+     *
+     * @param  array|int[]|string[]|Role|Role[]|Collection  $rolesOrIds
+     */
+    public function __construct(public Model $model, public mixed $rolesOrIds) {}
+}

src/Events/RoleDetached.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spatie\Permission\Events;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Collection;
+use Spatie\Permission\Contracts\Role;
+
+class RoleDetached
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    /**
+     * Internally the HasRoles trait passes $rolesOrIds as a single  Eloquent record
+     * Theoretically one could register the event to other places with an array etc
+     * So a Listener should inspect the type of $rolesOrIds received before using.
+     *
+     * @param  array|int[]|string[]|Role|Role[]|Collection  $rolesOrIds
+     */
+    public function __construct(public Model $model, public mixed $rolesOrIds) {}
+}

src/Traits/HasPermissions.php

@@ -9,6 +9,8 @@
 use Spatie\Permission\Contracts\Permission;
 use Spatie\Permission\Contracts\Role;
 use Spatie\Permission\Contracts\Wildcard;
+use Spatie\Permission\Events\PermissionAttached;
+use Spatie\Permission\Events\PermissionDetached;
 use Spatie\Permission\Exceptions\GuardDoesNotMatch;
 use Spatie\Permission\Exceptions\PermissionDoesNotExist;
 use Spatie\Permission\Exceptions\WildcardPermissionInvalidArgument;
@@ -423,6 +425,10 @@ function ($object) use ($permissions, $model, $teamPivot, &$saved) {
             $this->forgetCachedPermissions();
         }
 
+        if (config('permission.events_enabled')) {
+            event(new PermissionAttached($this->getModel(), $permissions));
+        }
+
         $this->forgetWildcardPermissionIndex();
 
         return $this;
@@ -460,12 +466,18 @@ public function syncPermissions(...$permissions)
      */
     public function revokePermissionTo($permission)
     {
-        $this->permissions()->detach($this->getStoredPermission($permission));
+        $storedPermission = $this->getStoredPermission($permission);
+
+        $this->permissions()->detach($storedPermission);
 
         if (is_a($this, Role::class)) {
             $this->forgetCachedPermissions();
         }
 
+        if (config('permission.events_enabled')) {
+            event(new PermissionDetached($this->getModel(), $storedPermission));
+        }
+
         $this->forgetWildcardPermissionIndex();
 
         $this->unsetRelation('permissions');

src/Traits/HasRoles.php

@@ -8,6 +8,8 @@
 use Illuminate\Support\Collection;
 use Spatie\Permission\Contracts\Permission;
 use Spatie\Permission\Contracts\Role;
+use Spatie\Permission\Events\RoleAttached;
+use Spatie\Permission\Events\RoleDetached;
 use Spatie\Permission\PermissionRegistrar;
 
 trait HasRoles
@@ -176,6 +178,10 @@ function ($object) use ($roles, $model, $teamPivot, &$saved) {
             $this->forgetCachedPermissions();
         }
 
+        if (config('permission.events_enabled')) {
+            event(new RoleAttached($this->getModel(), $roles));
+        }
+
         return $this;
     }
 
@@ -186,14 +192,20 @@ function ($object) use ($roles, $model, $teamPivot, &$saved) {
      */
     public function removeRole($role)
     {
-        $this->roles()->detach($this->getStoredRole($role));
+        $storedRole = $this->getStoredRole($role);
+
+        $this->roles()->detach($storedRole);
 
         $this->unsetRelation('roles');
 
         if (is_a($this, Permission::class)) {
             $this->forgetCachedPermissions();
         }
 
+        if (config('permission.events_enabled')) {
+            event(new RoleDetached($this->getModel(), $storedRole));
+        }
+
         return $this;
     }
 

tests/HasPermissionsTest.php

@@ -3,11 +3,15 @@
 namespace Spatie\Permission\Tests;
 
 use DB;
+use Illuminate\Support\Facades\Event;
 use Illuminate\Database\Eloquent\Model;
 use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\Attributes\Test;
 use Spatie\Permission\Contracts\Permission;
 use Spatie\Permission\Contracts\Role;
+use Spatie\Permission\Events\PermissionAttached;
+use Spatie\Permission\Events\PermissionDetached;
+use Spatie\Permission\Events\RoleAttached;
 use Spatie\Permission\Exceptions\GuardDoesNotMatch;
 use Spatie\Permission\Exceptions\PermissionDoesNotExist;
 use Spatie\Permission\Tests\TestModels\SoftDeletingUser;
@@ -824,6 +828,64 @@ public function it_can_reject_permission_based_on_logged_in_user_guard()
         ]);
     }
 
+    /** @test */
+    #[Test]
+    public function it_fires_an_event_when_a_permission_is_added()
+    {
+        Event::fake();
+        app('config')->set('permission.events_enabled', true);
+        
+        $this->testUser->givePermissionTo(['edit-articles', 'edit-news']);
+
+        $ids = app(Permission::class)::whereIn('name', ['edit-articles', 'edit-news'])
+            ->pluck($this->testUserPermission->getKeyName())
+            ->toArray();
+
+        Event::assertDispatched(PermissionAttached::class, function ($event) use ($ids) {
+            return $event->model instanceof User
+                && $event->model->hasPermissionTo('edit-news')
+                && $event->model->hasPermissionTo('edit-articles')
+                && $ids === $event->permissionsOrIds;
+        });
+    }
+
+    /** @test */
+    #[Test]
+    public function it_does_not_fire_an_event_when_events_are_not_enabled()
+    {
+        Event::fake();
+        app('config')->set('permission.events_enabled', false);
+        
+        $this->testUser->givePermissionTo(['edit-articles', 'edit-news']);
+
+        $ids = app(Permission::class)::whereIn('name', ['edit-articles', 'edit-news'])
+            ->pluck($this->testUserPermission->getKeyName())
+            ->toArray();
+
+        Event::assertNotDispatched(PermissionAttached::class);
+    }
+
+    /** @test */
+    #[Test]
+    public function it_fires_an_event_when_a_permission_is_removed()
+    {
+        Event::fake();
+        app('config')->set('permission.events_enabled', true);
+        
+        $permissions = app(Permission::class)::whereIn('name', ['edit-articles', 'edit-news'])->get();
+
+        $this->testUser->givePermissionTo($permissions);
+
+        $this->testUser->revokePermissionTo($permissions);
+
+        Event::assertDispatched(PermissionDetached::class, function ($event) use ($permissions) {
+            return $event->model instanceof User
+                && !$event->model->hasPermissionTo('edit-news')
+                && !$event->model->hasPermissionTo('edit-articles')
+                && $event->permissionsOrIds === $permissions;
+        });
+    }
+  
     /** @test */
     #[Test]
     public function it_can_be_given_a_permission_on_role_when_lazy_loading_is_restricted()

tests/HasRolesTest.php

@@ -4,10 +4,13 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Event;
 use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\Attributes\Test;
 use Spatie\Permission\Contracts\Permission;
 use Spatie\Permission\Contracts\Role;
+use Spatie\Permission\Events\RoleAttached;
+use Spatie\Permission\Events\RoleDetached;
 use Spatie\Permission\Exceptions\GuardDoesNotMatch;
 use Spatie\Permission\Exceptions\RoleDoesNotExist;
 use Spatie\Permission\Tests\TestModels\Admin;
@@ -917,6 +920,45 @@ public function it_does_not_detach_roles_when_user_soft_deleting()
         $this->assertTrue($user->hasRole('testRole'));
     }
 
+    /** @test */
+    #[Test]
+    public function it_fires_an_event_when_a_role_is_added()
+    {
+        Event::fake();
+        app('config')->set('permission.events_enabled', true);
+        
+        $this->testUser->assignRole(['testRole', 'testRole2']);
+
+        $roleIds = app(Role::class)::whereIn('name', ['testRole', 'testRole2'])
+            ->pluck($this->testUserRole->getKeyName())
+            ->toArray();
+
+        Event::assertDispatched(RoleAttached::class, function ($event) use ($roleIds) {
+            return $event->model instanceof User
+                && $event->model->hasRole('testRole')
+                && $event->model->hasRole('testRole2')
+                && $event->rolesOrIds === $roleIds;
+        });
+    }
+
+    /** @test */
+    #[Test]
+    public function it_fires_an_event_when_a_role_is_removed()
+    {
+        Event::fake();
+        app('config')->set('permission.events_enabled', true);
+        
+        $this->testUser->assignRole('testRole');
+
+        $this->testUser->removeRole('testRole');
+
+        Event::assertDispatched(RoleDetached::class, function ($event) {
+            return $event->model instanceof User
+                && !$event->model->hasRole('testRole')
+                && $event->rolesOrIds->name === 'testRole';
+        });
+    }
+  
     /** @test */
     #[Test]
     public function it_can_be_given_a_role_on_permission_when_lazy_loading_is_restricted()