README

A simple, flexible roles implementation for Laravel.

See v2.3 for Laravel 6-9 support.

Installation

Install with composer

$ composer require codinglabsau/laravel-roles

Publish migrations and migrate

php artisan vendor:publish --tag="roles-migrations"
php artisan migrate

Configuration

If you need to override the default Role model, you can do that by publishing the config and setting the models.role option.

php artisan vendor:publish --tag="roles-config"

Usage

Add the trait

Add the HasRoles trait to your user model:

use Codinglabs\Roles\HasRoles;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use Notifiable, HasRoles;
}

Create roles

$role = \Codinglabs\Roles\Role::create(['name' => 'manager']);

Get roles

$managerRole = \Codinglabs\Roles\Role::whereName('manager')->first();

Associate roles

Under the hood we are using Eloquent many-to-many relationships.

use Codinglabs\Roles\Role;

// attach multiple roles
$user->roles()->attach([
    Role::whereName('employee')->first()->id,
    Role::whereName('manager')->first()->id,
]);

// detach a single role
$user->roles()->detach(Role::whereName('employee')->first());

// update roles to match array
$user->roles()->sync([
    Role::whereName('employee')->first()->id,
]);

// ensure roles in array are attached without detaching others
$user->roles()->syncWithoutDetaching([
    Role::whereName('employee')->first()->id,
]);

Protect routes with middleware

In App\Http\Kernel, register the middeware:

protected $routeMiddleware = [
    // ...
    'role' => \Codinglabs\Roles\CheckRole::class,
];

And then call the middleware in your routes, seperating multiple roles with a pipe:

Route::middleware('role:employee')->...
Route::middleware('role:manager|admin')->...

Or with a gate:

class UserController extends Controller
{
    public function destroy()
    {
        $this->authorize('role', 'admin');
    }
}

Or in the constructor of a controller:

class ManagerDashboardController extends Controller
{
    public function __construct()
    {
        $this->middleware('role:manager');
    }
}

If the middleware check fails, a 403 response will be returned.

Check roles on a user

Call hasRole on the user model:

// check a single role
$user->hasRole('foo');

// check whether any role exists
$user->hasRole(['bar', 'baz']);

// get all roles
$user->roles;

Conditionally showing content with the blade directive

@role('admin')
<div>Super secret admin stuff goes here...</div>
@endrole

Sharing roles with UI (Inertiajs example)

// AppServiceProvider.php
Inertia::share([
    'auth' => function () {
        return [
            'user' => Auth::user() ? [
                'id' => Auth::user()->id,
                'roles' => Auth::user()->roles->pluck('name'),
            ] : null
        ];
    }
]);

// app.js
Vue.mixin({
  methods: {
    hasRole: function(role) {
      return this.$page.auth.user.roles.includes(role)
    }
  }
})

<!-- SomeComponent.vue -->
<div v-if="hasRole('manager')">I am a manager</div>

Upgrading from v1 to v2

Please see upgrading from v1 to v2 for details and instructions to avoid any issues after upgrading to v2.

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, create an issue on GitHub.

Credits

• Steve Thomas
• All Contributors

License

MIT. Please see the license file for more information.

About Coding Labs

Coding Labs is a web app development agency based on the Gold Coast, Australia. See our open source projects on our website.