jeremykenedy/laravel-roles

Table of contents

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

Features

• 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

Framework support

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.

Requirements

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

Installation

Composer

composer require jeremykenedy/laravel-roles

The service provider is discovered automatically.

The trait

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;
}

Migrations

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

Seeding

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.

Quick start

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');

Documentation

Full documentation lives in the docs folder.

Configuration

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.

The optional GUI

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.

Changing frameworks

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

Update (interactive)

php artisan roles:update

Or pass the option directly:

php artisan roles:update --css=bootstrap5

Switch (quick)

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

Artisan commands

Install options

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

Screenshots

These show the Bootstrap 4 interface.

Testing

composer test
composer lint

See the testing guide for what the suite covers.

License

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