Skip to content

Coming from Laravel ​

If you know spatie/laravel-permission, you already know most of RBAC Evolution. This page maps the Laravel concepts to their JS equivalents.

The main differences ​

  • Everything is async. Every method that touches storage returns a promise, so use await.
  • No model trait. Instead of $user->assignRole(), you scope the engine to a subject: rbac.for(user).assignRole(). A subject is a plain { type, id } object, so there is nothing to add to your user model.
  • One explicit instance. You create the engine with createRbac({ ... }). The options replace config/permission.php.
  • Guards and teams are passed per call as { guard, team } options, instead of being read from the auth guard or a global team id.

Concepts ​

Laravel / spatieRBAC Evolution
HasRoles trait on the User modelrbac.for({ type: 'user', id })
model_type + model_idSubject: { type, id }
guard_name{ guard: 'api' } option, default from defaultGuard
setPermissionsTeamId($teamId)rbac.for(user, { team: teamId })
config/permission.phpcreateRbac({ ... }) options
'teams' => truecreateRbac({ teams: true })
'enable_wildcard_permission' => truecreateRbac({ wildcard: true })
cache.expiration_time / cache.storecacheTtl (ms) / cache (a CacheStore)
Enums for role / permission namesTyped names: createRbac<{ permissions: ...; roles: ... }>()
Gate::before(...) super-adminbefore hook and superAdminRoles
Package events (RoleAttached, ...)rbac.on('role.attached', listener)

Tables ​

The Prisma and Drizzle adapters use the same five tables as spatie:

TableNotes
permissionsname, guard_name
rolesname, guard_name, team_id
role_has_permissionsLinks roles to permissions
model_has_rolessubject_type + subject_id instead of model_type + model_id
model_has_permissionsSame, for direct permissions

Roles and permissions ​

Laravel / spatieRBAC Evolution
Permission::create(['name' => 'edit articles'])rbac.createPermission('edit articles')
Role::create(['name' => 'writer'])rbac.createRole('writer')
Role::create([... 'guard_name' => 'api'])rbac.createRole('writer', { guard: 'api' })
Permission::findByName('edit articles')rbac.findPermissionOrFail('edit articles') (or findPermission, which returns null)
Role::findByName('writer')rbac.findRoleOrFail('writer') (or findRole)
Permission::findById($id) / Role::findById($id)rbac.findPermissionById(id) / rbac.findRoleById(id) (both return null when missing)
$permission->rolesrbac.rolesWithPermission('edit articles')
Permission::findOrCreate(...) / Role::findOrCreate(...)rbac.findOrCreatePermission(...) / rbac.findOrCreateRole(...)
Role::all() / Permission::all()rbac.getRoles() / rbac.getPermissions()
$role->delete()rbac.deleteRole('writer')
$role->givePermissionTo(...)rbac.role('writer').givePermissionTo(...)
$role->revokePermissionTo(...)rbac.role('writer').revokePermissionTo(...)
$role->syncPermissions(...)rbac.role('writer').syncPermissions(...)
$role->hasPermissionTo(...)rbac.role('writer').hasPermissionTo(...)

Users (subjects) ​

Laravel / spatieRBAC Evolution
$user->assignRole('writer')rbac.for(user).assignRole('writer')
$user->removeRole('writer')rbac.for(user).removeRole('writer')
$user->syncRoles([...])rbac.for(user).syncRoles([...])
$user->hasRole('writer')rbac.for(user).hasRole('writer')
$user->hasAnyRole(...) / hasAllRoles(...) / hasExactRoles(...)Same names on rbac.for(user)
$user->givePermissionTo(...)rbac.for(user).givePermissionTo(...)
$user->revokePermissionTo(...)rbac.for(user).revokePermissionTo(...)
$user->syncPermissions(...)rbac.for(user).syncPermissions(...)
$user->hasPermissionTo(...)rbac.for(user).hasPermissionTo(...)
$user->hasDirectPermission(...)rbac.for(user).hasDirectPermission(...)
$user->hasAnyDirectPermission(...) / hasAllDirectPermissions(...)Same names on rbac.for(user)
$user->checkPermissionTo(...)rbac.for(user).checkPermissionTo(...) (returns false instead of throwing)
$user->hasRole('admin', 'api') (guard argument)rbac.for(user).withScope({ guard: 'api' }).hasRole('admin')
$user->hasAnyPermission(...) / hasAllPermissions(...)Same names on rbac.for(user)
$user->can(...) / $user->cannot(...)rbac.for(user).can(...) / .cannot(...)
$user->canAny([...])rbac.for(user).canAny([...]) (plus canAll)
$user->getRoleNames()rbac.for(user).getRoleNames()
$user->getPermissionNames()rbac.for(user).getPermissionNames()
$user->getAllPermissions()rbac.for(user).getAllPermissions()
$user->getDirectPermissions()rbac.for(user).getDirectPermissions()
$user->getPermissionsViaRoles()rbac.for(user).getPermissionsViaRoles()
Role::syncModels([...])rbac.role('writer').syncSubjects('user', [...ids])
User::role('writer')->get()rbac.subjectsWithRole('user', 'writer') (returns ids)
User::permission('edit articles')->get()rbac.subjectsWithPermission('user', 'edit articles') (returns ids)
User::withoutRole('writer')->get()Query your users with id NOT IN (await rbac.subjectsWithRole('user', 'writer'))
User::withoutPermission(...)->get()Same, with subjectsWithPermission

Blade directives ​

BladeReact (-react)Vue (-vue)
@can('edit articles')<Can permission="edit articles">v-can="'edit articles'" or <Can permission="...">
@cannot('edit articles')<Cannot permission="edit articles">v-can.not="'edit articles'"
@canany([...])<Can anyOf={[...]}>v-can.any="[...]"
@role('admin')<HasRole role="admin">v-role="'admin'" or <HasRole role="admin">
@hasanyrole('admin|editor')<HasRole anyOf={['admin', 'editor']}>v-role="'admin|editor'"
@hasallroles('writer|editor')<HasRole allOf={['writer', 'editor']}>v-role.all="['writer', 'editor']"
@unlessrole('banned')<UnlessRole role="banned">v-role.not="'banned'"

Both packages work from a snapshot() sent by the server. See React and Vue.

Middleware ​

Laravel route middlewareExpress (-express)Next.js (-next)
role:adminrequireRole('admin')requireRole('admin') or a middleware rule { role: 'admin' }
permission:edit articlesrequirePermission('edit articles')requirePermission('edit articles') or { permission: '...' }
role_or_permission:admin|edit articlesrequireRoleOrPermission('admin|edit articles'){ roleOrPermission: ['admin', 'edit articles'] }
role:admin,api / permission:edit articles,api (another guard)requireRole('admin', { guard: 'api' })requireRole('admin', { guard: 'api' }) or withRbac(handler, { role: 'admin', guard: 'api' })

See Express and Next.js.

Artisan commands ​

ArtisanCLI
php artisan permission:create-permission "edit articles"npx rbac-evolution create-permission "edit articles"
php artisan permission:create-role writer web "edit articles"npx rbac-evolution create-role writer "edit articles" --guard web
php artisan permission:assign-role writer 1npx rbac-evolution assign-role writer 1
php artisan permission:shownpx rbac-evolution show
php artisan permission:cache-resetnpx rbac-evolution cache-reset

The spatie-style names (permission:create-role, ...) are accepted as aliases. See CLI.

Cache and exceptions ​

Laravel / spatieRBAC Evolution
app(PermissionRegistrar::class)->forgetCachedPermissions()rbac.forgetCachedPermissions()
PermissionDoesNotExistPermissionDoesNotExist
RoleDoesNotExistRoleDoesNotExist
PermissionAlreadyExists / RoleAlreadyExistsSame names
GuardDoesNotMatchGuardDoesNotMatch

All errors extend RbacError and have a code field. See Errors.

Released under the MIT License. Inspired by spatie/laravel-permission.