Permissions via roles
A role is a named group of permissions. Give permissions to the role once, then assign the role to as many subjects as you like. When the role changes, everyone who has it is affected.
Giving permissions to a role
Use rbac.role() to work with a single role:
await rbac.createPermission('edit articles')
await rbac.createPermission('delete articles')
await rbac.createRole('writer')
const writer = rbac.role('writer')
await writer.givePermissionTo('edit articles', 'delete articles')
await writer.revokePermissionTo('delete articles')
await writer.syncPermissions(['edit articles']) // replace all permissions of the rolerbac.role() accepts a name or a Role object. It doesn't query anything until you call a method; an unknown role name throws RoleDoesNotExist at that point.
Reading and checking:
await writer.getPermissions() // Permission[]
await writer.getPermissionNames() // ['edit articles']
await writer.hasPermissionTo('edit articles') // true
await writer.get() // the Role object, or throws RoleDoesNotExistAssigning roles
const user = rbac.for({ type: 'user', id: 1 })
await user.assignRole('writer')
await user.assignRole('writer', 'editor')
await user.assignRole(['writer', 'editor'])
await user.removeRole('editor')Assigning a role the subject already has is a no-op. An unknown role name throws RoleDoesNotExist.
Syncing roles
syncRoles() makes the given roles the subject's only roles:
await user.syncRoles('editor') // now only 'editor'
await user.syncRoles(['a', 'b']) // now only 'a' and 'b'
await user.syncRoles() // no roles at allSyncing only affects roles in the current guard and team.
From the role's side, syncSubjects() makes the given subjects of one type the role's only holders (spatie Role::syncModels()). Other subject types keep the role. role.attached / role.detached events fire per subject.
await rbac.role('editor').syncSubjects('user', [2, 7]) // only users 2 and 7 are editors nowChecking roles
await user.hasRole('writer') // has this role
await user.hasRole(['writer', 'editor']) // has ANY of these roles
await user.hasAnyRole('writer', 'editor') // has at least one
await user.hasAllRoles('writer', 'editor') // has both
await user.hasExactRoles('writer', 'editor') // has both, and no other roleRole checks never throw. A role that doesn't exist is simply not one the subject has.
INFO
Role checks are data checks. They are not affected by the before hook or super-admin roles.
Reading roles
await user.getRoleNames() // ['writer', 'editor']
await user.getRoles() // Role[]Checking permissions that come from roles
Permission checks look at direct permissions and at the permissions of all the subject's roles:
await rbac.role('writer').givePermissionTo('edit articles')
await user.assignRole('writer')
await user.can('edit articles') // true
await user.hasPermissionTo('edit articles') // true
await user.hasDirectPermission('edit articles') // false: it comes from a role
await user.getPermissionsViaRoles() // [{ name: 'edit articles', ... }]Finding subjects by role
To list everyone who has a role, ask the engine for subject ids of a given type:
await rbac.subjectsWithRole('user', 'writer') // e.g. [1, 4]
await rbac.subjectsWithRole('user', ['writer', 'editor']) // any of the roles
await rbac.subjectsWithPermission('user', 'edit articles') // directly or via a roleUnknown names throw RoleDoesNotExist / PermissionDoesNotExist. See Querying subjects for details.
