Add support for configurable role identifier key (e.g., slug)

Author: alexphila

config/permission.php

@@ -26,7 +26,14 @@
 
         'role' => Spatie\Permission\Models\Role::class,
 
-    ],
+    ],    
+    
+    /*
+     * This option defines which column on the roles table is used to identify a role
+     * when checking things like $user->hasRole('admin').
+     * By default, it uses 'name', but you can change this to 'slug' or any other unique column.
+     */
+    'role_identifier' => 'name',
 
     'table_names' => [
 

database/migrations/create_permission_tables.php.stub

@@ -38,6 +38,7 @@ return new class extends Migration
                 $table->index($columnNames['team_foreign_key'], 'roles_team_foreign_key_index');
             }
             $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
+            $table->string('slug')->nullable();
             $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
             $table->timestamps();
             if ($teams || config('permission.testing')) {

src/Models/Role.php

@@ -126,6 +126,28 @@ public static function findById(int|string $id, ?string $guardName = null): Role
         return $role;
     }
 
+    /**
+     * Find a role by its configured key (e.g. name or slug) and guard name.
+     *
+     * @return RoleContract|Role
+     *
+     * @throws RoleDoesNotExist
+     */
+    public static function findByKey(string $value, ?string $guardName = null): RoleContract
+    {
+        $guardName = $guardName ?? Guard::getDefaultName(static::class);
+        $key = config('permission.role_identifier', 'name');
+
+        $role = static::findByParam([$key => $value, 'guard_name' => $guardName]);
+
+        if (! $role) {
+            throw RoleDoesNotExist::named($value, $guardName);
+        }
+
+        return $role;
+    }
+
+
     /**
      * Find or create role by its name (and optionally guardName).
      *

src/Traits/HasRoles.php

@@ -238,6 +238,8 @@ public function syncRoles(...$roles)
      */
     public function hasRole($roles, ?string $guard = null): bool
     {
+        $roleKey = $this->getRoleKey();
+
         $this->loadMissing('roles');
 
         if (is_string($roles) && strpos($roles, '|') !== false) {
@@ -249,7 +251,7 @@ public function hasRole($roles, ?string $guard = null): bool
 
             return $this->roles
                 ->when($guard, fn ($q) => $q->where('guard_name', $guard))
-                ->pluck('name')
+                ->pluck($roleKey)
                 ->contains(function ($name) use ($roles) {
                     /** @var string|\BackedEnum $name */
                     if ($name instanceof \BackedEnum) {
@@ -270,8 +272,8 @@ public function hasRole($roles, ?string $guard = null): bool
 
         if (is_string($roles)) {
             return $guard
-                ? $this->roles->where('guard_name', $guard)->contains('name', $roles)
-                : $this->roles->contains('name', $roles);
+                ? $this->roles->where('guard_name', $guard)->contains($roleKey, $roles)
+                : $this->roles->contains($roleKey, $roles);
         }
 
         if ($roles instanceof Role) {
@@ -314,6 +316,8 @@ public function hasAnyRole(...$roles): bool
      */
     public function hasAllRoles($roles, ?string $guard = null): bool
     {
+        $roleKey = $this->getRoleKey();
+
         $this->loadMissing('roles');
 
         if ($roles instanceof \BackedEnum) {
@@ -332,16 +336,16 @@ public function hasAllRoles($roles, ?string $guard = null): bool
             return $this->roles->contains($roles->getKeyName(), $roles->getKey());
         }
 
-        $roles = collect()->make($roles)->map(function ($role) {
+        $roles = collect()->make($roles)->map(function ($role) use ($roleKey) {
             if ($role instanceof \BackedEnum) {
                 return $role->value;
             }
 
-            return $role instanceof Role ? $role->name : $role;
+            return $role instanceof Role ? $role->{$roleKey} : $role;
         });
 
         $roleNames = $guard
-            ? $this->roles->where('guard_name', $guard)->pluck('name')
+            ? $this->roles->where('guard_name', $guard)->pluck($roleKey)
             : $this->getRoleNames();
 
         $roleNames = $roleNames->transform(function ($roleName) {
@@ -362,6 +366,8 @@ public function hasAllRoles($roles, ?string $guard = null): bool
      */
     public function hasExactRoles($roles, ?string $guard = null): bool
     {
+        $roleKey = $this->getRoleKey();
+
         $this->loadMissing('roles');
 
         if (is_string($roles) && strpos($roles, '|') !== false) {
@@ -373,10 +379,10 @@ public function hasExactRoles($roles, ?string $guard = null): bool
         }
 
         if ($roles instanceof Role) {
-            $roles = [$roles->name];
+            $roles = [$roles->{$roleKey}];
         }
 
-        $roles = collect()->make($roles)->map(fn ($role) => $role instanceof Role ? $role->name : $role
+        $roles = collect()->make($roles)->map(fn ($role) => $role instanceof Role ? $role->{$roleKey} : $role
         );
 
         return $this->roles->count() == $roles->count() && $this->hasAllRoles($roles, $guard);
@@ -390,11 +396,17 @@ public function getDirectPermissions(): Collection
         return $this->permissions;
     }
 
+    /**
+     * Return all role identifiers for the model.
+     *
+     * Note: This respects the configured 'role_identifier' column (e.g., 'name' or 'slug'),
+     * even though the method name is 'getRoleNames' for backward compatibility.
+     */
     public function getRoleNames(): Collection
     {
         $this->loadMissing('roles');
 
-        return $this->roles->pluck('name');
+        return $this->roles->pluck($this->getRoleKey());
     }
 
     protected function getStoredRole($role): Role
@@ -408,7 +420,7 @@ protected function getStoredRole($role): Role
         }
 
         if (is_string($role)) {
-            return $this->getRoleClass()::findByName($role, $this->getDefaultGuardName());
+            return $this->getRoleClass()::findByKey($role, $this->getDefaultGuardName());
         }
 
         return $role;
@@ -435,4 +447,10 @@ protected function convertPipeToArray(string $pipeString)
 
         return explode('|', trim($pipeString, $quoteCharacter));
     }
+
+    protected function getRoleKey(): string
+    {
+        return config('permission.role_identifier', 'name');
+    }
+
 }

tests/HasRolesTest.php

@@ -46,6 +46,56 @@ public function it_can_determine_that_the_user_does_not_have_a_role()
         $role = app(Role::class)->findOrCreate('testRoleInWebGuard2', 'web');
         $this->assertFalse($this->testUser->hasRole($role));
     }
+    
+    /** @test */
+    #[Test]
+    public function test_has_role_with_default_identifier()
+    {
+        config(['permission.role_identifier' => 'name']);
+
+        $user = User::create(['email' => '[email protected]']);
+
+        app(Role::class)->create(['name' => 'Editor', 'slug' => 'editor', 'guard_name' => 'web']);
+
+        $user->assignRole('Editor');
+
+        $this->assertTrue($user->hasRole('Editor'));
+        $this->assertFalse($user->hasRole('editor')); // slug shouldn't work
+    }
+
+    /** @test */
+    #[Test]
+    public function test_has_role_with_slug_identifier()
+    {
+        config(['permission.role_identifier' => 'slug']);
+
+        $user = User::create(['email' => '[email protected]']);
+
+        app(Role::class)->create(['name' => 'Editor', 'slug' => 'editor', 'guard_name' => 'web']);
+
+        $user->assignRole('editor');
+
+        $this->assertTrue($user->hasRole('editor'));
+        $this->assertFalse($user->hasRole('Editor')); // name shouldn't work
+    }
+
+    /** @test */
+    #[Test]
+    public function test_has_all_roles_with_slug_identifier()
+    {
+        config(['permission.role_identifier' => 'slug']);
+
+        $user = User::create(['email' => '[email protected]']);
+
+        app(Role::class)->create(['name' => 'Admin', 'slug' => 'admin', 'guard_name' => 'web']);
+        app(Role::class)->create(['name' => 'Manager', 'slug' => 'manager', 'guard_name' => 'web']);
+
+        $user->assignRole('admin', 'manager');
+
+        $this->assertTrue($user->hasAllRoles(['admin', 'manager']));
+        $this->assertTrue($user->hasExactRoles(['admin', 'manager']));
+        $this->assertFalse($user->hasExactRoles(['admin']));
+    }
 
     /**
      * @test