laravel-roles

Role-Based Access Control (RBAC) for Laravel. Roles, permissions and role levels. Supports Laravel 5.3 through 13.

• Features
• Framework support
• Requirements
• Installation
  • Composer
  • The trait
  • Migrations
  • Seeding
• Quick start
• Documentation
• Configuration
• The optional GUI
• Changing frameworks
• Artisan commands
• Screenshots
• Testing
• License

• Roles with levels, and permissions attached to roles or directly to users
• Permission inheritance from lower level roles, which can be turned off
• Entity checks, so a user can act on a model they own without a permission
• Four Blade directives and three route middleware
• Soft deletes with restore and force delete
• An optional CRUD interface in Bootstrap 4, Bootstrap 5 or Tailwind CSS
• An optional JSON API
• Every table name, model and behaviour configurable from the environment

The optional GUI ships three complete view sets. Exactly one is active at a time, chosen with ROLES_CSS_FRAMEWORK.

Bootstrap 4 is the default and is the markup this package has always shipped, so upgrading does not change the look of an existing install.

Continuous integration covers PHP 8.2 through 8.4 on Laravel 12 and 13.

composer require jeremykenedy/laravel-roles

The service provider is discovered automatically.

Add the trait to the model auth.providers.users.model points at:

use Illuminate\Foundation\Auth\User as Authenticatable;
use jeremykenedy\LaravelRoles\Traits\HasRoleAndPermission;

class User extends Authenticatable
{
    use HasRoleAndPermission;
}

Run the shipped migrations by turning them on:

ROLES_MIGRATION_DEFAULT_ENABLED=true

php artisan migrate

Or publish them first and keep them under your own version control:

php artisan vendor:publish --tag=laravelroles-migrations
php artisan migrate

Publish the seeders and call them from your own DatabaseSeeder:

php artisan vendor:publish --tag=laravelroles-seeds
composer dump-autoload
php artisan db:seed

Full detail, including running the shipped seeders without publishing, is in the seeding guide.

use jeremykenedy\LaravelRoles\Models\Permission;
use jeremykenedy\LaravelRoles\Models\Role;

$admin = Role::create([
    'name'        => 'Admin',
    'slug'        => 'admin',
    'description' => 'Full access',
    'level'       => 5,
]);

$permission = Permission::create([
    'name'  => 'Can Edit Users',
    'slug'  => 'edit.users',
    'model' => 'Permission',
]);

$admin->attachPermission($permission);
$user->attachRole($admin);

Then check it:

$user->hasRole('admin');            // true
$user->hasPermission('edit.users'); // true
$user->level();                     // 5
$user->isAdmin();                   // true
$user->canEditUsers();              // true

In a view:

@role('admin')
    Only an admin sees this.
@endrole

On a route:

Route::get('/admin', fn () => view('admin'))->middleware('role:admin');

Full documentation lives in the docs folder.

php artisan vendor:publish --tag=laravelroles-config

Every option reads from an environment variable, so most installs never edit the config file. The ones reached for most often:

The complete list, including every table name, model, front end asset and access control option, is in the configuration guide.

ROLES_GUI_ENABLED=true

That registers the CRUD routes for roles and permissions, including the soft delete dashboards. The views extend the layout named by ROLES_GUI_BLADE_EXTENDED, which defaults to layouts.app, and your layout needs to yield the sections the views render into:

@yield('inline_template_linked_css')
...
@yield('inline_footer_scripts')

Access is gated by Laravel's auth middleware and by role:admin, both of which are configurable. See the GUI guide for the full route list and access control options.

After installation, use update or switch to change the CSS framework without losing configuration.

php artisan roles:update

Or pass the option directly:

php artisan roles:update --css=bootstrap5

php artisan roles:switch --css=tailwind

If you published the views, republish them for the framework you moved to:

php artisan vendor:publish --tag=laravelroles-views-tailwind --force

Passing --css skips the prompts, so the commands work unattended in a deploy script. Full detail in the commands guide.

These show the Bootstrap 4 interface.

Roles dashboard	Create a role

Edit a role	Role detail

Delete a role	Deleted role detail

Restore a role	Deleted roles dashboard

Permissions dashboard	Create a permission

Permission detail	Deleted permissions dashboard

composer test
composer lint

See the testing guide for what the suite covers.

This package is open-sourced software licensed under the MIT license.