siberfx / rbac-permission
Scope-aware roles and permissions for Laravel: module.resource.verb@scope grants, a scope ladder, query constraints, and HTTP, console, Gate and Blade enforcement with an explainable decision trace.
Requires
- php: ^8.4
- illuminate/auth: ^12.0 || ^13.0
- illuminate/cache: ^12.0 || ^13.0
- illuminate/console: ^12.0 || ^13.0
- illuminate/contracts: ^12.0 || ^13.0
- illuminate/database: ^12.0 || ^13.0
- illuminate/events: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/routing: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- illuminate/view: ^12.0 || ^13.0
Requires (Dev)
- backpack/crud: ^7.0.47
- filament/filament: ^5.8.3
- orchestra/testbench: ^10.0 || ^11.0
- pestphp/pest: ^3.8 || ^4.0
- pestphp/pest-plugin-laravel: ^3.2 || ^4.0
Suggests
- backpack/crud: Adds RBAC access control to Backpack CRUD controllers and a user model for the Backpack guard (^7.0.47).
- filament/filament: Adds the RBAC role screens and the user roles relation manager for Filament panels (^5.8.3).
Provides
None
Conflicts
None
Replaces
None
README
π‘οΈ RBAC Permission for Laravel
Roles, permissions and scopes that say who may act and how far the reach goes.
billing.invoice.edit@team
Who Β· What Β· How far
Why it's different β’ Quick start β’ Permission grammar β’ Scopes β’ Enforcement β’ Commands β’ Configuration β’ Testing
β¨ Why it's different
Most permission packages answer one question: can this user do X? Real applications need a second one: on which records?
RBAC Permission makes the answer to both a single string:
billing.invoice.edit@team
βββββββ¬ββββββ ββββ¬βββ βββ¬ββ
module resource verb what you may do
@team how far the reach goes
- π§ Scopes are first class.
own,team,tenantandglobalare a ladder. A grant at a wider scope covers every record a narrower one does. - π One rule, every layer. The same grant works for a single record check, a list query, a Gate call, a Blade directive, a route, a service method and a console command.
- π§© Lists stay correct.
Rbac::constrain()turns "can see invoices at team scope" into the exactWHEREclause. No row leaks, no manual filtering. - β Denies always win. A direct deny on one user overrides every role they hold.
- π Every decision is explainable.
rbac:explainandRbac::explain()show which roles and grants were considered and which one covered the record. - π§Ύ Roles as code. Describe roles in
config/rbac.php, runrbac:sync, and review changes in pull requests. - π§± Fails loudly. A typo like
billing.invoice.flyis rejected at write time and at check time, never silently ignored. - π οΈ Adjustable. Add verbs, modules, scopes and resolvers without touching package code.
It fits a small blog, a multi-team SaaS, or an enterprise back office with the same vocabulary.
βοΈ How it compares
A quick look against spatie/laravel-permission, the most widely used Laravel permission package.
| Area | Spatie laravel-permission | RBAC Permission |
|---|---|---|
| Permission model | Flat names, such as edit articles |
module.resource.verb@scope, such as billing.invoice.edit@team |
| Record-level reach | Not built in. Write the check per model or policy | Built in: own, team, tenant, global scope ladder |
| List filtering | Not built in. Add where clauses yourself |
Rbac::constrain() produces the exact WHERE clause |
| Wildcards | Supported | Segment wildcards, such as billing.*@tenant |
| Multi-tenancy | Teams support, enabled through config | Scope ladder, with team and tenant as scopes |
| Deny overrides | Not built in. Access is only granted | Denies always win over allows |
| Catalog of allowed names | Not built in. Unknown names throw when assigned | Permissions must be listed in the catalog, so typos are rejected |
| Explaining decisions | Not built in | rbac:explain and Rbac::explain() show every grant considered |
| Role hierarchy | Not built in | Ranks: actors can only manage roles below their own rank |
| Time-limited access | Not built in | Built in: expires_at on roles and direct grants |
| Audit | Not built in | Events, with an optional audit table |
| Multiple guards | Supported | Supported: roles belong to a guard, and a user model picks its guard |
| Admin screens | Not built in. Available through third-party panels | Built in: Blade role and assignment screens (optional, off by default) |
| Filament integration | Not built in. Available through third-party plugins | Optional RbacPlugin for Filament 5: role screens, grant editor, user roles relation manager |
| Backpack integration | Not built in. Available through third-party packages | Built in: HasRbacAccess for CRUD controllers, HasBackpackRbac for admin users |
| Ecosystem | Large user base, many third-party integrations, years of production use | New (v1.x), small user base, few integrations |
Choose Spatie for a standard, well-supported permission system with flat rules and a large ecosystem, or when you need to use it with a wide range of third-party packages.
Choose RBAC Permission when access depends on which records a user may reach, when lists must be filtered by team or tenant, when you need to explain decisions, when you want hierarchy, expiry and an audit trail built in, or when you need admin screens for roles and assignments.
Spatie's feature list reflects its documentation at the time of writing. Check its current docs before deciding.
π Quick start
1. Install
composer require siberfx/rbac-permission
2. Publish and run the migration
php artisan vendor:publish --tag=rbac-migrations php artisan migrate
3. Add the trait to your user model
use Siberfx\RbacPermission\Concerns\HasRbac; class User extends Authenticatable { use HasRbac; }
4. Describe your permissions and roles in config/rbac.php (see Configuration), then sync them:
php artisan rbac:sync
5. Use it
$user->assignRole('manager'); $user->can('billing.invoice.edit', $invoice); // record check, through Gate Rbac::allows('billing.invoice.edit', $invoice); // same answer, anywhere Rbac::constrain(Invoice::query(), 'billing.invoice.show')->paginate(); // only rows I may see
𧬠The permission grammar
Every permission is written the same way, and wildcards work in grants:
| Grant | Meaning |
|---|---|
billing.invoice.edit@team |
Edit invoices, for records in the user's team |
billing.invoice.*@tenant |
Every invoice verb, across the whole tenant |
billing.*@own |
Every billing permission, only on records the user owns |
*.invoice.show@global |
Show invoices anywhere, in any module |
*@global |
Everything (super administrator) |
A trailing * covers the rest of the key. A * in the middle matches exactly one segment.
The verbs
| Verb | Use it for |
|---|---|
access |
Entering an area, page or module |
show |
Reading a record or a view |
create |
Making a new record |
edit |
Changing an existing record |
delete |
Removing a record |
run |
Executing an action, job, command or report |
export |
Taking data out of the system |
approve |
Signing off a pending change |
Add your own (for example publish or impersonate) in config('rbac.verbs').
πͺ The scope ladder
Scopes answer where. Each one is a small class with two jobs: decide whether a single record is covered, and narrow a query to the covered rows.
global ββββββββββββββββββββββββββββββββββββββ every record
tenant ββββββββββββββββββββββββββ the user's tenant
team ββββββββββββββ the user's teams
own ββββββ records the user owns
| Scope | Covers a record when⦠| Adds to a query |
|---|---|---|
own |
the owner column equals the user | WHERE user_id = ? |
team |
the team column is one of the user's teams | WHERE team_id IN (β¦) |
tenant |
the tenant column equals the user's tenant | WHERE tenant_id = ? |
global |
always | nothing |
Add your own scope, such as region, in three steps: write a class that implements ScopeContract, register it under rbac.scopes with a level, and use it in a grant. A level decides which scope counts as "widest" in matrices and reports.
π§ Enforcement everywhere
Models and Eloquent
Add HasRbacScopes to resource models whose column names differ from the defaults:
use Siberfx\RbacPermission\Concerns\HasRbacScopes; class Invoice extends Model { use HasRbacScopes; public function rbacOwnerColumn(): string { return 'created_by'; } public function rbacTeamColumn(): string { return 'department_id'; } }
Gate and policies
Every catalog permission works with the standard authorization API:
$user->can('billing.invoice.edit', $invoice); Gate::allows('billing.invoice.approve', $refund); $this->authorize('billing.invoice.show', $invoice);
Names outside the catalog are left to your own gates, so the two systems coexist.
Blade
@rbac('billing.invoice.edit', $invoice) <a href="{{ route('invoices.edit', $invoice) }}">Edit</a> @else <span class="muted">Read only</span> @endrbac
Use
@else, not@elserbac. Blade's@elserbacis anelseifwith no arguments.
HTTP routes
Put the permission on the action, and the route stays clean:
use Siberfx\RbacPermission\Attributes\RequiresPermission; class InvoiceController { #[RequiresPermission('billing.invoice.show', subject: 'invoice')] public function show(Invoice $invoice) { /* ... */ } #[RequiresPermission('billing.invoice.delete', subject: 'invoice')] public function destroy(Invoice $invoice) { /* ... */ } }
Route::get('/invoices/{invoice}', [InvoiceController::class, 'show'])->middleware('rbac');
Or state it on the route:
Route::get('/legacy/{invoice}', ...)->middleware('rbac:billing.invoice.show,invoice');
A scoped check must receive a real model. If the route parameter cannot be bound, the request fails closed with an error rather than being treated as a list check.
Services and jobs
use Siberfx\RbacPermission\Facades\Rbac; public function approve(Refund $refund): void { Rbac::enforce('billing.refund.approve', $refund); // throws PermissionDenied (403) // ... approve the refund }
Lists and exports
$invoices = Rbac::constrain(Invoice::query(), 'billing.invoice.show') ->latest() ->paginate();
The scope becomes SQL. Combined grants are unioned, and a direct deny is applied as NOT (β¦).
Console commands
use Siberfx\RbacPermission\Attributes\RequiresPermission; #[RequiresPermission('ops.cache.run')] class ClearCache extends Command { protected $signature = 'ops:cache-clear'; // ... }
The command runs as the user named in RBAC_CONSOLE_USER_ID. If that user lacks the permission, the command is refused before its body runs. Unattended runs, such as cron jobs without an actor, are refused as well unless you set allow_unattended to true.
π Explain a decision
When access is denied and nobody knows why, ask the system:
php artisan rbac:explain billing.invoice.edit 42 --on-model="App\Models\Invoice" --on=7
Example output:
Decision: ALLOW
User: App\Models\User#42
Subject: Invoice#7
Roles: manager
+----------------------------------+-----------------+----------------+
| Grant | Source | Covers subject |
+----------------------------------+-----------------+----------------+
| billing.invoice.edit@team | role:manager | yes |
| deny billing.invoice.edit@own | direct | no |
+----------------------------------+-----------------+----------------+
The exit code is 0 when allowed and 1 when denied, so it works in scripts and CI. In code, use Rbac::explain() to get the same trace as an array.
π₯οΈ Admin screens
An optional Blade UI for roles, role grants and user role assignments. It is off by default.
// config/rbac.php 'ui' => [ 'enabled' => true, 'prefix' => 'rbac', // served at /rbac/roles 'middleware' => ['web', 'auth'], ],
Every action checks a catalog permission:
| Permission | Lets the user |
|---|---|
admin.role.show |
View roles and their grants |
admin.role.edit |
Add or remove grants on a role |
admin.user.show |
View a user's roles |
admin.user.edit |
Assign or remove a user's roles |
A role editor can only add a grant they already hold at that scope or wider, enforced by Rbac::canGrant(). Role assignment follows the rank rules, so an admin cannot hand out a role at their own rank or higher.
The screens are plain Blade with no CDN assets, and they follow light and dark mode. They are a starting point. To change the look, publish the views with php artisan vendor:publish --tag=rbac-views. They are then loaded from resources/views/vendor/rbac.
If your admin is built on Filament, use the Filament integration below instead.
π§© Filament integration
For Filament 5 panels. Install Filament, then add the plugin to a panel:
composer require filament/filament:^5.8.3
use Siberfx\RbacPermission\Filament\RbacPlugin; public function panel(Panel $panel): Panel { return $panel ->default() ->id('admin') ->path('admin') ->plugin(RbacPlugin::make()); // adds the Roles resource }
To show a user's roles and assign them from your user resource, add the relation manager:
use Siberfx\RbacPermission\Filament\Resources\UserRolesRelationManager; public static function getRelations(): array { return [UserRolesRelationManager::class]; // the user model must use HasRbac }
What the screens do:
- Roles lists every role of every guard. Editing a role changes its name, description and rank. Role slugs and grants come from
config/rbac.phpthroughrbac:sync, and the screen manages grants in a relation manager. - Grants can be added and removed. The signed-in user must hold each grant at that scope or wider (
Rbac::canGrant()), so a role editor cannot hand out access they lack. - Ranks cannot be set at or above your own rank, and you can only edit roles below your rank.
- Assignments follow the same rank rules. Expiry is optional.
- The Roles resource does not offer create or delete. Create roles in
config/rbac.phpand runrbac:sync.
Access uses the catalog permissions from the admin screens (admin.role.show, admin.role.edit, admin.user.show, admin.user.edit). The Roles resource is hidden from users who do not hold them.
RbacPlugin and the relation manager use the signed-in user from Filament's guard (Filament::auth()).
π§± Backpack integration
For Backpack for Laravel 7. Install Backpack, then use the two traits below.
1. The admin user keeps its roles in Backpack's own guard (backpack.base.guard), so the admins stay separate from your app's users:
use Siberfx\RbacPermission\Backpack\HasBackpackRbac; class BackpackUser extends Authenticatable { use HasBackpackRbac; }
Sync the roles of that guard with rbac.guards, for example 'backpack' => ['roles' => [...]], then run php artisan rbac:sync.
2. Each CRUD controller checks the catalog permissions for its resource:
use Siberfx\RbacPermission\Backpack\HasRbacAccess; class InvoiceCrudController extends CrudController { use HasRbacAccess; protected ?string $rbacResource = 'billing.invoice'; public function setup(): void { CRUD::setModel(Invoice::class); // ... fields, columns, operations ... $this->applyRbacAccess(); // call last } }
What it does:
| Backpack operation | Catalog permission |
|---|---|
list, show |
{resource}.show |
create, store |
{resource}.create |
update, edit, reorder |
{resource}.edit |
delete |
{resource}.delete |
- The list is narrowed to the rows the admin may reach (
Rbac::constrain()), so scope rules apply to the table, not just to single pages. - Single records are checked against their scope, so an admin with
billing.invoice.edit@owncan edit only their own invoices. - Access rules already set on the panel (for example
$this->crud->denyAccess('delete')) still apply.
The admin user is the one signed in on the Backpack guard (backpack_auth()).
π§° Commands
| Command | What it does |
|---|---|
rbac:sync [--prune] [--guard=] |
Writes the roles from config/rbac.php to the database in one transaction, for every guard (or only --guard). --prune removes roles that are no longer defined. |
rbac:matrix [--only-granted] [--guard=] |
Prints the role by permission grid for one guard, showing the widest scope of each grant. |
rbac:explain {permission} {user} [--on-model= --on=] |
Explains a decision, with the grants that were considered. |
rbac:assign {role} {user} [--revoke] [--expires=] |
Gives or removes a role for a user. --expires makes the role time-boxed. |
rbac:grant {role} {permission} [--revoke] [--guard=] |
Adds or removes a grant on a role. The role is created if it is missing. |
php artisan rbac:matrix
Example output:
+------------------------------+------------+---------+-------+
| Permission | manager | staff | super |
+------------------------------+------------+---------+-------+
| billing.invoice.show | team | own | global|
| billing.invoice.edit | team | own | global|
| billing.invoice.delete | - | - | global|
| ops.cache.run | - | - | global|
+------------------------------+------------+---------+-------+
π§βπΌ Managing access in code
use Siberfx\RbacPermission\Facades\Rbac; Rbac::role('auditor', 'Auditor', 'Read-only access across billing'); Rbac::grant('auditor', 'billing.*@tenant'); Rbac::grant('auditor', 'reports.sales.export@tenant'); $user->assignRole('auditor'); $user->removeRole('staff'); $user->allowPermission('billing.refund.approve@global'); // direct allow $user->denyPermission('billing.invoice.delete@own'); // direct deny, always wins $user->withdrawPermission('billing.invoice.delete@own'); // remove the override Rbac::widestScope('billing.invoice.show', $user); // "tenant"
Every write clears the grant cache for the request, and when caching is enabled it invalidates the cache for everyone.
Role hierarchy
Give each role a rank in rbac.ranks. An actor may only assign or remove a role whose rank is strictly below the highest rank they hold, so an admin can hand out manager but never admin.
$admin = auth()->user(); // holds "admin" (rank 80) $target->assignRole('manager', by: $admin); // allowed (50 < 80) $target->assignRole('admin', by: $admin); // throws RoleAssignmentDenied (80 is not below 80) Rbac::rankOf($admin); // 80
Without by: nothing is checked, which is how seeders and trusted jobs run. rbac:assign checks against the configured console actor (rbac.console).
Multiple guards
Roles belong to an authentication guard. Each user model says which guard it uses, and roles are resolved within it. So manager can mean one thing for web users and another for admin users.
// config/rbac.php: the default guard uses the top-level roles and ranks 'guards' => [ 'admin' => [ 'roles' => ['manager' => ['billing.*@tenant']], 'ranks' => ['manager' => 50], ], ],
class Admin extends Authenticatable { use HasRbac; public function rbacGuard(): string { return 'admin'; // HasRbac defaults to auth.defaults.guard } } $admin->assignRole('manager'); // resolved in the admin guard $web->assignRole('manager'); // resolved in the default guard
Checks without an explicit user use the guard that is logged in. Pass the user yourself when several guards are active at once. Route middleware always uses $request->user(), so it follows the route's guard.
Time-boxed grants
Roles and direct overrides accept an optional expiry. Once it passes, the grant stops applying, with no job needed.
$user->assignRole('manager', expiresAt: now()->addDays(30)); // covering for a colleague $user->allowPermission('billing.refund.approve@global', now()->addHours(4)); $user->denyPermission('billing.invoice.delete@own', now()->addDay()); // temporary lock-out Rbac::pruneExpired(); // optional: delete expired rows, e.g. from a daily schedule
php artisan rbac:assign staff 42 --expires="+7 days"
Expired rows are ignored at once, even if they are still in the table. Assigning a role again without an expiry makes it permanent.
When the grant cache is enabled (rbac.cache.ttl > 0), a grant can keep applying for up to ttl seconds after it expires. Keep the TTL short if that matters to you.
Audit log
Every change to roles, assignments and direct grants fires Siberfx\RbacPermission\Events\RbacChanged. Turn on rbac.audit.enabled to also store each change in rbac_audit_logs:
// config/rbac.php 'audit' => ['enabled' => true],
action |
Fired when |
|---|---|
role.granted / role.revoked |
A permission is added to or removed from a role |
role.assigned / role.unassigned |
A role is given to or removed from a user |
permission.allowed / permission.denied / permission.withdrawn |
A direct override is written or removed |
roles.synced |
rbac:sync or Rbac::sync() runs |
grants.pruned |
Rbac::pruneExpired() removes expired rows |
Each row stores the actor (the by: user if you passed one, otherwise the authenticated user), the subject, and the permission, scope, effect and expiry involved. Changes that remove nothing are not recorded.
Listen for the event for your own reporting or notifications:
Event::listen(RbacChanged::class, function (RbacChanged $event) { if ($event->action === 'role.assigned') { Log::info('role assigned', ['by' => $event->actor?->getKey(), 'to' => $event->subject?->getKey()]); } });
Audit writes run inside the same request as the change. If the change is in a database transaction that rolls back, its audit row rolls back too.
βοΈ Configuration
Publish the file to change anything:
php artisan vendor:publish --tag=rbac-config
| Key | Purpose |
|---|---|
tables |
Table names, if they clash with yours |
default_scope |
Scope used when a grant has no @scope. Default: own |
verbs |
The allowed verb vocabulary |
modules |
The catalog of every permission in your application |
scopes |
The scope ladder: name, level, resolver class |
columns |
Default owner, team and tenant columns on resource models |
user.teams_relation |
Relation on the user that returns teams |
roles |
Roles as code, applied with rbac:sync |
console |
Console actor and unattended policy |
cache |
Optional cross-request grant cache (ttl in seconds, 0 disables) |
register_gate |
Whether catalog permissions are registered with the Gate |
A complete example of modules and roles
'modules' => [ 'billing' => [ 'label' => 'Billing', 'resources' => [ 'invoice' => ['show', 'create', 'edit', 'delete', 'export', 'approve'], 'refund' => ['show', 'create', 'approve'], ], ], 'ops' => [ 'label' => 'Operations', 'resources' => [ 'cache' => ['run'], ], ], ], 'roles' => [ 'super-admin' => ['*@global'], 'admin' => ['billing.*@tenant'], 'manager' => [ 'billing.invoice.show@team', 'billing.invoice.edit@team', 'billing.invoice.approve@team', ], 'staff' => [ 'billing.invoice.show@own', 'billing.invoice.create@own', 'billing.invoice.edit@own', ], ],
ποΈ Database schema
| Table | Holds |
|---|---|
rbac_roles |
Role slug, guard, name, description and rank (slug is unique per guard) |
rbac_role_grants |
The permission and scope each role carries |
rbac_role_assignments |
Which user holds which role, and until when (polymorphic) |
rbac_user_grants |
Direct allows and denies on a user, and until when (polymorphic) |
rbac_audit_logs |
Change history, when rbac.audit.enabled is true |
Model ids are stored as strings, so integer, UUID and ULID keys all work.
π§ͺ Testing
The package is tested with Pest on Testbench, with an in-memory SQLite database.
composer install
composer test
Or run it directly:
vendor/bin/pest
The suite covers the grammar and wildcards, every scope and deny overrides, query constraints, Gate and Blade integration, HTTP enforcement from attributes and route arguments, console guarding, roles as code, the matrix and explanations.
In your own application, reset the grant cache between tests if you enable it:
Rbac::flush();
πΊοΈ Roadmap
- Role hierarchy with "can only assign roles below mine" (v1.1.0)
- Time-boxed grants (
expires_at) (v1.2.0) - Permission audit log through the event system (v1.3.0)
Ideas and pull requests are welcome.
π€ Contributing
- Fork the repository and create a feature branch.
- Add a Pest test that fails without your change.
- Run
composer testand make sure it passes. - Open a pull request with a clear description.
Please follow Semantic Versioning for releases. Notable changes go into CHANGELOG.md.
π·οΈ Versioning and releases
Releases are tagged on main with a v prefix, for example v1.0.0. Install a specific version with a constraint:
composer require siberfx/rbac-permission:^1.0
Each release is listed on the Releases page with its changes.
π€ Author
Selim Gormus Β· @siberfx Β· info@siberfx.com
π License
The MIT License (MIT). See LICENSE.md for details.
If this package saves you time, a β on GitHub helps others find it.