PHPackages                             miracuthbert/laravel-roles - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. miracuthbert/laravel-roles

ActiveLibrary[Authentication & Authorization](/categories/authentication)

miracuthbert/laravel-roles
==========================

An Eloquent roles and permissions package for Laravel 5.8 and up

1.10.0(5mo ago)21.6k[6 PRs](https://github.com/miracuthbert/laravel-roles/pulls)MITPHPPHP ^7.3|^8.0

Since Nov 11Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/miracuthbert/laravel-roles)[ Packagist](https://packagist.org/packages/miracuthbert/laravel-roles)[ RSS](/packages/miracuthbert-laravel-roles/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (7)Versions (33)Used By (0)

Laravel Roles
=============

[](#laravel-roles)

An Eloquent roles and permissions package for Laravel 5.8 and up.

Installation
------------

[](#installation)

To can install the package via composer:

```
composer require miracuthbert/laravel-roles

```

Setup
-----

[](#setup)

The package takes advantage of Laravel Auto-Discovery, so it doesn't require you to manually add the ServiceProvider.

If you don't use auto-discovery, add the ServiceProvider to the providers array in config/app.php

```
Miracuthbert\LaravelRoles\LaravelRolesServiceProvider::class
```

### Migrations

[](#migrations)

You first need to publish the packages migrations:

```
php artisan vendor:publish --tag=laravel-roles-migrations

```

For those who had published migrations earlier use command(s) below to publish updated changes:

```
php artisan vendor:publish --tag=laravel-roles-permitable-migrations

```

Then run the migrate command:

```
php artisan migrate

```

### Seeding

[](#seeding)

By default the package includes a seeder for roles and permissions, `RolesAndPermissionsTableSeeder`.

You can add it to your `DatabaseSeeder` or use the command below to run it in isolation.

```
php artisan db:seed --class=\Miracuthbert\LaravelRoles\Database\Seeders\RolesAndPermissionsTableSeeder

```

> See the [usage](#usage) section on how to assign a role to a user via the console.

Configuration
-------------

[](#configuration)

To customize the package usage, copy the package config to your local config by using the publish command:

```
php artisan vendor:publish --tag=laravel-roles-config

```

The package includes configuration for:

### Role Sharing

[](#role-sharing)

`allow_shared_roles` key enables the package to query for roles that can be shared by [models](#models).

Example, an `admin` role for `Team` model can be shared and easily managed by the app admin, compared to a `manager` role that may vary between teams.

### User Model

[](#user-model)

The default user model is `App\Models\User::class` the default namespace of `User` model.

You can change the default user model by changing `model` key under `users` in the config file.

> See the [usage](#usage) section on how to enable roles and permissions on the User model.

### Middleware

[](#middleware)

Under middleware you can configure the `abort_code`, which by default is `403`.

### Permitable Types

[](#permitable-types)

You can setup the types of role and permissions allowed to be created within your app.

This can be useful in a multi-tenant app for filtering out `Admin` and `Tenant` based permissions and roles.

For example if your application has `teams` and each member performs unique tasks you can define a permission or role type `team` under `permitables` in the config file which can be used to filter out only `team` permissions or roles.

```
'team' => 'Team'
```

> Permitable types for non admin roles need to be linked to added as a key in the models array in the config file.

### Models

[](#models)

You can also map `permitables` types (mentioned above) to related models.

```
'team' => \App\Models\Team::class
```

> Each model can only be related to a single permitable type.

Usage
-----

[](#usage)

To start assigning roles and permissions to users, you must first add the `LaravelRolesUserTrait` trait to the `User` model.

> The User model should match the one indicated in the package's config file. See [configuration](#configuration).

### Assigning a Role

[](#assigning-a-role)

#### Basic

[](#basic)

To assign a role to a user you can call the `assignRole` method on a User model instance.

The `assignRole` method accepts a `role` (Role model instance), `expiresAt` a date which is optional and `giver` an instance Eloquent Model among `models` registered in [configuration](#models) which is optional.

```
$user->assignRole($role, $expiresAt, $giver);
```

> The expiresAt value must be a future date.

> giver value can omitted when role assigned belongs to a registered model

#### Via Console

[](#via-console)

To assign role via console use command below, passing in a registered User's `email` and a valid Role `slug`.

For example a user with email `johndoe@example.org` and a Role named `Admin Root` with slug `admin-root` will be:

```
php artisan role:assign johndoe@example.org admin-root

```

> You can seed the roles and permissions table with the seeder that comes with the package. See [Seeding](#seeding).

### Revoking a Role

[](#revoking-a-role)

Revoking a role is the same as assign, where the `revokeRoleAt` method is called on a User model instance.

The method accepts a `role` (Role model instance) and `expiresAt` a date which is optional.

> If the expiresAt date is not given the role will be revoked immediately.

```
$user->revokeRoleAt($role, $expiresAt);
```

### Revoking all Roles

[](#revoking-all-roles)

To revoke all roles from a user, call the `revokeRoles` method on a User model instance.

The method accepts an optional array of `roles` (or a collection of Role model instances).

> If no value is passed to method, the user's valid roles will be revoked.

*Note:* Revoking a role just set's the expired timestamp, not deleting the history of user's roles.

```
$user->revokeRoles();

// with an array of values
$user->revokeRoles(['admin-root', 'admin-basic']);
```

### Detaching all Roles

[](#detaching-all-roles)

To detach all roles from a user, call the `detachRoles` method on a User model instance.

The method accepts an optional array of `roles` (or a collection of Role model instances).

> Detaching roles from a user with completely delete the history of user's roles.

```
$user->detachRoles();

// with an array of values
$user->detachRoles(['admin-root', 'admin-basic']);
```

Authorization
-------------

[](#authorization)

There are various ways you can authorize a user using the package:

### Roles

[](#roles)

To check a user has a valid role use the `slug` of a valid Role model.

> The role must be `usable` (active).

#### Via User Model

[](#via-user-model)

```
if($user->hasRole('admin-root')) {
    // user can do something as admin
}
```

Checking for multiple roles:

```
if($user->hasRole(['admin-root', 'manager', 'editor'])) {
    // user can do something as admin
}
```

Or

```
if($user->hasRole('admin-root', 'manager', 'editor')) {
    // user can do something as admin
}
```

#### Via Blade Helpers

[](#via-blade-helpers)

```
@role('admin-root')

@endrole
```

#### Middleware

[](#middleware-1)

You can user the `role` middleware to check if user has access.

It accepts a role `slug` and permission `slug` or `name`.

##### In Routes

[](#in-routes)

```
// Just role
Route::middleware(['role:admin-root'])->get('/admin/logs');

// Via role and permission
Route::middleware(['role:admin-root,delete-admins'])->delete('/admin/roles/editors/revoke');
```

##### In Controller

[](#in-controller)

```
public function __construct() {
    // Via permission name `browse admin`
    $this->middleware(['role:admin-root']);

    // Via role and permission (slug or name)
    $this->middleware(['role:admin-root,delete-admins']);
}
```

> See permissions section to learn how to authorize a user via permissions.

### Permissions

[](#permissions)

To check a user has access via permission use a `slug` or `name` of a valid Permission model.

eg. a permission named `browse admin` can be passed as `browse-admin` or `browse admin`.

> The permission must be `usable` (active).

An additional parameter `giver` is accepted, if you have to check for permissions based on the model that assigned it.

For example, to check a user has a permission through a role of type `team`:

- You can be pass an instance of `Team` model
- Or pass a type with a corresponding id: `team:1`.

Whether the `id` is a `slug` or a basic `id`, it will be resolved by the package.

> When passing a type make sure it has a corresponding model registered under the package's config in the `models` key.

#### Via Gates

[](#via-gates)

```
if(Gate::allows('browse-admin')) {
    // do something
}

// With giver
if(Gate::allows('browse-admin', $team)) {
    // do something
}
```

```
if(Gate::denies('browse-admin')) {
    return abort(403);
}

// With giver
if(Gate::denies('browse-admin', $team)) {
    return abort(403);
}
```

#### Via User model

[](#via-user-model-1)

```
if($user->can('assign roles')) {
    // do something
}

// With giver
if($user->can('assign roles', $team)) {
    // do something
}
```

#### Via Blade Helpers

[](#via-blade-helpers-1)

```
@can('impersonate user')

@endcan

// With giver
@can('impersonate user', $team)

@endcan
```

```
@cannot('impersonate user')

@endcannot

// With giver
@cannot('impersonate user', $team)

@endcannot
```

#### Middleware

[](#middleware-2)

Using middleware there are two ways:

##### In Routes

[](#in-routes-1)

```
// Via permission name `browse admin`
Route::middleware(['permission: browse admin'])->get('/admin/dashboard');

// Via permission slug `browse-admin`
Route::middleware(['permission: browse-admin'])->get('/admin/dashboard');
```

##### In Controller

[](#in-controller-1)

```
public function __construct() {
    // Via permission name `browse admin`
    $this->middleware(['permission: browse admin']);

    // Via permission slug `browse-admin`
    $this->middleware(['permission: browse-admin']);

    // Via permission name `browse admin` with giver, the id should be fetched from the request or dynamically resolved
    $this->middleware(['permission: browse admin, team:' . $request->team]);

    // Via permission slug `browse-admin` with giver, the id should be fetched from the request or dynamically resolved
    $this->middleware(['permission: browse-admin, team:' . $request->team]);
}
```

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability, please send an e-mail to Cuthbert Mirambo via . All security vulnerabilities will be promptly addressed.

Credits
-------

[](#credits)

- [Cuthbert Mirambo](https://github.com/miracuthbert)

License
-------

[](#license)

The project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance73

Regular maintenance activity

Popularity20

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity73

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~88 days

Recently: every ~263 days

Total

26

Last Release

153d ago

PHP version history (3 changes)1.0.0PHP ^7.1.3

1.6.0PHP >=7.3.0

1.8.0PHP ^7.3|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6a7cd612359c9e02072f9270834f3cddf8de0464cf1b6313b6b2aa9ab95a0df6?d=identicon)[miracuthbert](/maintainers/miracuthbert)

---

Top Contributors

[![miracuthbert](https://avatars.githubusercontent.com/u/13046285?v=4)](https://github.com/miracuthbert "miracuthbert (38 commits)")

---

Tags

laravellaravel-packagepermissionsroleslaravelrolespermissions

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/miracuthbert-laravel-roles/health.svg)

```
[![Health](https://phpackages.com/badges/miracuthbert-laravel-roles/health.svg)](https://phpackages.com/packages/miracuthbert-laravel-roles)
```

###  Alternatives

[hasinhayder/tyro

Tyro - The ultimate Authentication, Authorization, and Role & Privilege Management solution for Laravel 12 & 13

6712.1k2](/packages/hasinhayder-tyro)[beatswitch/lock-laravel

A Laravel Driver for Lock.

15529.1k1](/packages/beatswitch-lock-laravel)[scaler-tech/laravel-saml2

SAML2 Service Provider integration for Laravel applications, based on OneLogin toolkit

2737.5k](/packages/scaler-tech-laravel-saml2)[pingpong/trusty

Roles and Permissions for Laravel 4

2680.0k9](/packages/pingpong-trusty)[wnikk/laravel-access-rules

Simple system of ACR (access control rules) for Laravel, with roles, groups, unlimited inheritance and possibility of multiplayer use.

103.6k1](/packages/wnikk-laravel-access-rules)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)