Download the PHP package artisanpack-ui/rbac without Composer

ArtisanPack UI — RBAC

Role-based access control for Laravel: roles with hierarchy, permissions, Blade directives, middleware, and Gate integration.

This package is standalone — it does not depend on artisanpack-ui/security and can be used by any Laravel application or package (e.g. cms-framework) that needs roles and permissions without pulling in the full security suite.

Features

• Eloquent Role and Permission models with parent/child role hierarchy
• HasRoles and HasPermissions traits for the User model
• Recursive permission resolution through the role hierarchy, with per-user caching
• Route middleware (permission:slug,slug) for permission-gated routes
• @role and @permission Blade directives
• Gate integration ($user->can('slug'), Gate::allows('slug'), @can('slug')) backed by RBAC permissions
• Artisan commands for CRUD over roles and role assignments
• Configurable model bindings so consumers can extend Role / Permission with their own subclasses
• Eloquent observer events on the rbac.* channel for downstream auditing

Installation

Run the package migrations:

(Optional) Publish the config file to override model bindings, table names, or cache settings:

Quick start

Add the traits to your User model:

Create a role + permission and assign them:

Models

Role

ArtisanPackUI\Rbac\Models\Role

Relationships:

• permissions() → BelongsToMany Permission
• users() → BelongsToMany against auth.providers.users.model
• parent() → BelongsTo Role
• children() → HasMany Role

Slug helpers: Role::findBySlug('editor'), Role::whereSlug('editor')->first(). hasRole('editor') and assignRole('editor') match against either name or slug.

Deleting a role detaches its permissions and nulls parent_id on its children.

Permission

ArtisanPackUI\Rbac\Models\Permission

Relationships:

• roles() → BelongsToMany Role

Slug helpers: Permission::findBySlug('pages.publish'), Permission::whereSlug('pages.publish')->first(). hasPermissionTo('pages.publish') and the Gate integration both match against either name or slug.

Deleting a permission detaches it from all roles.

Traits

HasRoles

Adds the roles() relationship plus assignment helpers.

assignRole and removeRole dispatch the rbac.user.role_assigned and rbac.user.role_removed events with the user and role.

HasPermissions

Resolves the user's effective permission set by walking the role hierarchy. Pair with HasRoles.

The trait caches the resolved permission collection per user. The cache TTL is configurable via artisanpack.rbac.cache.user_permissions_ttl.

Middleware

The service provider aliases permission to ArtisanPackUI\Rbac\Http\Middleware\CheckPermission. Apply it to routes that require one or more permissions — the user must hold at least one to proceed.

Unauthenticated requests abort with 401, authorized requests return 200, and authenticated requests without any of the listed permissions abort with 403.

Blade directives

Both directives render nothing for unauthenticated users.

@permission resolves through the user's effective permission set, which means it composes with role hierarchy. Use Laravel's built-in @can directive when you want the same check to flow through the Gate integration:

Gate integration

The service provider registers a Gate::before hook that resolves any ability matching a known permission slug through hasPermissionTo(). Standard Laravel authorization patterns work out of the box:

Abilities that don't correspond to an RBAC permission slug fall through to the normal Gate/Policy lookup, so policies you've defined elsewhere continue to work.

The list of known permission slugs is cached for artisanpack.rbac.cache.permission_names_ttl seconds. The cache is invalidated automatically when permissions are created, updated, or deleted.

Artisan commands

{user} accepts a numeric ID or any value that matches one of the configured user_lookup_fields (defaults to email). The assign/revoke commands are idempotent.

Configuration reference

Published to config/artisanpack/rbac.php.

Extending the base models

Other packages can extend Role and Permission and rebind them through config — useful when a downstream package needs extra relationships or scopes without forking this package. The cms-framework package uses this pattern for its Users module.

The Artisan commands, observers, traits, and migrations all read this config, so the substituted class is used everywhere.

Events

The service provider attaches observers that dispatch:

• rbac.role.created, rbac.role.updated, rbac.role.deleted
• rbac.permission.created, rbac.permission.updated, rbac.permission.deleted

Pivot mutations are dispatched directly from the trait helpers since Laravel does not fire pivot events:

• rbac.user.role_assigned, rbac.user.role_removed

Listen for these in any application or sibling package — security-analytics uses them for audit logging.

Testing

Tests run against an in-memory SQLite database via Orchestra Testbench. The package's own test suite covers role / permission models, traits, middleware, Artisan commands, Blade directives, Gate integration, observers, and the configurable model-binding pattern.

Sibling packages

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute.