PHPackages                             xetaio/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. xetaio/roles

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

xetaio/roles
============

Powerful package for handling roles and permissions in Laravel 5.

9.0.0(4y ago)07.5kMITPHPPHP >=7.3

Since Jan 15Pushed 4y agoCompare

[ Source](https://github.com/XetaIO/roles)[ Packagist](https://packagist.org/packages/xetaio/roles)[ RSS](/packages/xetaio-roles/feed)WikiDiscussions master Synced today

READMEChangelog (5)Dependencies (7)Versions (54)Used By (0)

> # Roles And Permissions
>
> [](#roles-and-permissions)
>
> Unit TestsCoverageStable VersionDownloadsLaravelLicense[![GitHub Workflow Status](https://camo.githubusercontent.com/2dde6d9466136aa026a6eeaf43666db5b0e834097bda46af21a71f107cf92586/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f58657461494f2f526f6c65732f556e697425323054657374733f7374796c653d666c61742d737175617265)](https://github.com/XetaIO/Roles/actions/workflows/tests.yml)[![Coverage Status](https://camo.githubusercontent.com/c22a4b8579f03c1ffe11c61eb4ce38516da3db7ce64e33bf82ae79505419413d/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f58657461494f2f726f6c65733f7374796c653d666c61742d737175617265)](https://app.codecov.io/gh/XetaIO/roles)[![Latest Stable Version](https://camo.githubusercontent.com/a68893d658ec83ff252224b0a478bedc3aa6f97af5fcb903320d4a28c2413ccb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f58657461494f2f726f6c65732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xetaio/roles)[![Total Downloads](https://camo.githubusercontent.com/ad73fe96332509289157720820ace21f5c4f38de008fd2f248a55f98e6b7fbec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f78657461696f2f726f6c65732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xetaio/roles)[![Laravel 8.0](https://camo.githubusercontent.com/4be469918d81757bbfce0d8ba7b2efccbc3a867a51c95b789ca194c40d03f7ed/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d2533453d382e302d6634363435662e7376673f7374796c653d666c61742d737175617265)](http://laravel.com)[![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/XetaIO/roles/blob/master/LICENSE)Powerful package for handling roles and permissions in Laravel.
>
> - [Installation](#installation)
>     - [Composer](#composer)
>     - [Service Provider](#service-provider)
>     - [Config File And Migrations](#config-file-and-migrations)
>     - [HasRoleAndPermission Trait And Contract](#hasroleandpermission-trait-and-contract)
>     - [Migrate from Bican roles](#Migrate-from-bican-roles)
> - [Usage](#usage)
>     - [Creating Roles](#creating-roles)
>     - [Attaching, Detaching and Syncing Roles](#attaching-detaching-and-syncing-roles)
>     - [Checking For Roles](#checking-for-roles)
>     - [Levels](#levels)
>     - [Creating Permissions](#creating-permissions)
>     - [Attaching, Detaching and Syncing Permissions](#attaching-detaching-and-syncing-permissions)
>     - [Checking For Permissions](#checking-for-permissions)
>     - [Permissions Inheriting](#permissions-inheriting)
>     - [Entity Check](#entity-check)
>     - [Blade Extensions](#blade-extensions)
>     - [Middleware](#middleware)
> - [Config File](#config-file)
> - [More Information](#more-information)
> - [License](#license)
>
> ## Installation
>
> [](#installation)
>
> This package is very easy to set up. There are only couple of steps.
>
> ### Composer
>
> [](#composer)
>
> Pull this package in through Composer
>
> ```
> composer require ultraware/roles
>
> ```
>
>
>
> If you are still using Laravel 5.0, you must pull in version `1.7.*`.
>
> ### Service Provider
>
> [](#service-provider)
>
> Add the package to your application service providers in `config/app.php` file.
>
> ```
> 'providers' => [
>
>    ...
>
>    /**
>     * Third Party Service Providers...
>     */
>    Ultraware\Roles\RolesServiceProvider::class,
>
> ],
> ```

### Config File And Migrations

[](#config-file-and-migrations)

Publish the package config file and migrations to your application. Run these commands inside your terminal.

```
php artisan vendor:publish --provider="Ultraware\Roles\RolesServiceProvider" --tag=config
php artisan vendor:publish --provider="Ultraware\Roles\RolesServiceProvider" --tag=migrations

```

And also run migrations.

```
php artisan migrate

```

> This uses the default users table which is in Laravel. You should already have the migration file for the users table available and migrated.

### HasRoleAndPermission Trait And Contract

[](#hasroleandpermission-trait-and-contract)

Include `HasRoleAndPermission` trait and also implement `HasRoleAndPermission` contract inside your `User` model.

Migrate from bican roles
------------------------

[](#migrate-from-bican-roles)

If you migrate from bican/roles to ultraware/roles yoe need to update a few things.

- Change all calls to `can`, `canOne` and `canAll` to `hasPermission`, `hasOnePermission`, `hasAllPermissions`.
- Change all calls to `is`, `isOne` and `isAll` to `hasRole`, `hasOneRole`, `hasAllRoles`.

Usage
-----

[](#usage)

### Creating Roles

[](#creating-roles)

```
use Ultraware\Roles\Models\Role;

$adminRole = Role::create([
    'name' => 'Admin',
    'slug' => 'admin',
    'description' => '', // optional
    'level' => 1, // optional, set to 1 by default
]);

$moderatorRole = Role::create([
    'name' => 'Forum Moderator',
    'slug' => 'forum.moderator',
]);
```

> Because of `Slugable` trait, if you make a mistake and for example leave a space in slug parameter, it'll be replaced with a dot automatically, because of `str_slug` function.

### Attaching, Detaching and Syncing Roles

[](#attaching-detaching-and-syncing-roles)

It's really simple. You fetch a user from database and call `attachRole` method. There is `BelongsToMany` relationship between `User` and `Role` model.

```
use App\User;

$user = User::find($id);

$user->attachRole($adminRole); // you can pass whole object, or just an id
$user->detachRole($adminRole); // in case you want to detach role
$user->detachAllRoles(); // in case you want to detach all roles
$user->syncRoles($roles); // you can pass Eloquent collection, or just an array of ids
```

### Checking For Roles

[](#checking-for-roles)

You can now check if the user has required role.

```
if ($user->hasRole('admin')) { // you can pass an id or slug
    //
}
```

You can also do this:

```
if ($user->isAdmin()) {
    //
}
```

And of course, there is a way to check for multiple roles:

```
if ($user->hasRole(['admin', 'moderator'])) {
    /*
    | Or alternatively:
    | $user->hasRole('admin, moderator'), $user->hasRole('admin|moderator'),
    | $user->hasOneRole('admin, moderator'), $user->hasOneRole(['admin', 'moderator']), $user->hasOneRole('admin|moderator')
    */

    // The user has at least one of the roles
}

if ($user->hasRole(['admin', 'moderator'], true)) {
    /*
    | Or alternatively:
    | $user->hasRole('admin, moderator', true), $user->hasRole('admin|moderator', true),
    | $user->hasAllRoles('admin, moderator'), $user->hasAllRoles(['admin', 'moderator']), $user->hasAllRoles('admin|moderator')
    */

    // The user has all roles
}
```

### Levels

[](#levels)

When you are creating roles, there is optional parameter `level`. It is set to `1` by default, but you can overwrite it and then you can do something like this:

```
if ($user->level() > 4) {
    //
}
```

> If user has multiple roles, method `level` returns the highest one.

`Level` has also big effect on inheriting permissions. About it later.

### Creating Permissions

[](#creating-permissions)

It's very simple thanks to `Permission` model.

```
use Ultraware\Roles\Models\Permission;

$createUsersPermission = Permission::create([
    'name' => 'Create users',
    'slug' => 'create.users',
    'description' => '', // optional
]);

$deleteUsersPermission = Permission::create([
    'name' => 'Delete users',
    'slug' => 'delete.users',
]);
```

### Attaching, Detaching and Syncing Permissions

[](#attaching-detaching-and-syncing-permissions)

You can attach permissions to a role or directly to a specific user (and of course detach them as well).

```
use App\User;
use Ultraware\Roles\Models\Role;

$role = Role::find($roleId);
$role->attachPermission($createUsersPermission); // permission attached to a role

$user = User::find($userId);
$user->attachPermission($deleteUsersPermission); // permission attached to a user
```

```
$role->detachPermission($createUsersPermission); // in case you want to detach permission
$role->detachAllPermissions(); // in case you want to detach all permissions
$role->syncPermissions($permissions); // you can pass Eloquent collection, or just an array of ids

$user->detachPermission($deleteUsersPermission);
$user->detachAllPermissions();
$user->syncPermissions($permissions); // you can pass Eloquent collection, or just an array of ids
```

### Checking For Permissions

[](#checking-for-permissions)

```
if ($user->hasPermission('create.users')) { // you can pass an id or slug
    //
}

if ($user->canDeleteUsers()) {
    //
}
```

You can check for multiple permissions the same way as roles. You can make use of additional methods like `hasOnePermission` or `hasAllPermissions`.

### Permissions Inheriting

[](#permissions-inheriting)

Role with higher level is inheriting permission from roles with lower level.

There is an example of this `magic`:

You have three roles: `user`, `moderator` and `admin`. User has a permission to read articles, moderator can manage comments and admin can create articles. User has a level 1, moderator level 2 and admin level 3. It means, moderator and administrator has also permission to read articles, but administrator can manage comments as well.

> If you don't want permissions inheriting feature in you application, simply ignore `level` parameter when you're creating roles.

### Entity Check

[](#entity-check)

Let's say you have an article and you want to edit it. This article belongs to a user (there is a column `user_id` in articles table).

```
use App\Article;
use Ultraware\Roles\Models\Permission;

$editArticlesPermission = Permission::create([
    'name' => 'Edit articles',
    'slug' => 'edit.articles',
    'model' => 'App\Article',
]);

$user->attachPermission($editArticlesPermission);

$article = Article::find(1);

if ($user->allowed('edit.articles', $article)) { // $user->allowedEditArticles($article)
    //
}
```

This condition checks if the current user is the owner of article. If not, it will be looking inside user permissions for a row we created before.

```
if ($user->allowed('edit.articles', $article, false)) { // now owner check is disabled
    //
}
```

### Blade Extensions

[](#blade-extensions)

There are four Blade extensions. Basically, it is replacement for classic if statements.

```
@role('admin') // @if(Auth::check() && Auth::user()->hasRole('admin'))
    // user has admin role
@endrole

@permission('edit.articles') // @if(Auth::check() && Auth::user()->hasPermission('edit.articles'))
    // user has edit articles permissison
@endpermission

@level(2) // @if(Auth::check() && Auth::user()->level() >= 2)
    // user has level 2 or higher
@endlevel

@allowed('edit', $article) // @if(Auth::check() && Auth::user()->allowed('edit', $article))
    // show edit button
@endallowed

@role('admin|moderator', true) // @if(Auth::check() && Auth::user()->hasRole('admin|moderator', true))
    // user has admin and moderator role
@else
    // something else
@endrole
```

### Middleware

[](#middleware)

This package comes with `VerifyRole`, `VerifyPermission` and `VerifyLevel` middleware. You must add them inside your `app/Http/Kernel.php` file.

```
/**
 * The application's route middleware.
 *
 * @var array
 */
protected $routeMiddleware = [
    'auth' => \App\Http\Middleware\Authenticate::class,
    'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
    'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
    'role' => \Ultraware\Roles\Middleware\VerifyRole::class,
    'permission' => \Ultraware\Roles\Middleware\VerifyPermission::class,
    'level' => \Ultraware\Roles\Middleware\VerifyLevel::class,
];
```

Now you can easily protect your routes.

```
$router->get('/example', [
    'as' => 'example',
    'middleware' => 'role:admin',
    'uses' => 'ExampleController@index',
]);

$router->post('/example', [
    'as' => 'example',
    'middleware' => 'permission:edit.articles',
    'uses' => 'ExampleController@index',
]);

$router->get('/example', [
    'as' => 'example',
    'middleware' => 'level:2', // level >= 2
    'uses' => 'ExampleController@index',
]);
```

It throws `\Ultraware\Roles\Exceptions\RoleDeniedException`, `\Ultraware\Roles\Exceptions\PermissionDeniedException` or `\Ultraware\Roles\Exceptions\LevelDeniedException` exceptions if it goes wrong.

You can catch these exceptions inside `app/Exceptions/Handler.php` file and do whatever you want.

```
/**
 * Render an exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Exception  $e
 * @return \Illuminate\Http\Response
 */
public function render($request, Exception $e)
{
    if ($e instanceof \Ultraware\Roles\Exceptions\RoleDeniedException) {
        // you can for example flash message, redirect...
        return redirect()->back();
    }

    return parent::render($request, $e);
}
```

Config File
-----------

[](#config-file)

You can change connection for models, slug separator, models path and there is also a handy pretend feature. Have a look at config file for more information.

More Information
----------------

[](#more-information)

For more information, please have a look at [HasRoleAndPermission](https://github.com/ultraware/roles/blob/master/src/Contracts/HasRoleAndPermission.php) contract.

License
-------

[](#license)

This package is free software distributed under the terms of the MIT license.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity22

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 52.5% 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 ~50 days

Recently: every ~222 days

Total

53

Last Release

1503d ago

Major Versions

2.1.7 → 5.1.02016-12-01

5.8.0 → 6.0.02019-10-26

6.0.0 → 7.0.02020-08-02

7.0.0 → 8.0.02022-03-22

8.0.0 → 9.0.02022-03-30

PHP version history (9 changes)0.9PHP >=5.4.0

2.0.0PHP >=5.5.9

5.1.0PHP >=5.6.4

5.5.x-devPHP >=7.0.0

5.6.0PHP >=7.1.3

5.8.0PHP >=7.2

7.0.0PHP >=7.2.5

8.0.0PHP ^7.3|^8.0

9.0.0PHP >=7.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/b411de63e10c9029d2d06da585856f15db12c23395bc908f085fad15638a8098?d=identicon)[Xety](/maintainers/Xety)

---

Top Contributors

[![romanbican](https://avatars.githubusercontent.com/u/6573175?v=4)](https://github.com/romanbican "romanbican (96 commits)")[![Ricky-rick](https://avatars.githubusercontent.com/u/9480194?v=4)](https://github.com/Ricky-rick "Ricky-rick (49 commits)")[![Xety](https://avatars.githubusercontent.com/u/8210023?v=4)](https://github.com/Xety "Xety (11 commits)")[![lucasmichot](https://avatars.githubusercontent.com/u/513603?v=4)](https://github.com/lucasmichot "lucasmichot (7 commits)")[![interphased](https://avatars.githubusercontent.com/u/1676931?v=4)](https://github.com/interphased "interphased (4 commits)")[![Kyslik](https://avatars.githubusercontent.com/u/2067589?v=4)](https://github.com/Kyslik "Kyslik (3 commits)")[![lucidlemon](https://avatars.githubusercontent.com/u/2458762?v=4)](https://github.com/lucidlemon "lucidlemon (2 commits)")[![bbashy](https://avatars.githubusercontent.com/u/1149200?v=4)](https://github.com/bbashy "bbashy (2 commits)")[![williamoliveira](https://avatars.githubusercontent.com/u/6340344?v=4)](https://github.com/williamoliveira "williamoliveira (1 commits)")[![Yangwendaxia](https://avatars.githubusercontent.com/u/3424048?v=4)](https://github.com/Yangwendaxia "Yangwendaxia (1 commits)")[![branchzero](https://avatars.githubusercontent.com/u/7685609?v=4)](https://github.com/branchzero "branchzero (1 commits)")[![greggilbert](https://avatars.githubusercontent.com/u/169482?v=4)](https://github.com/greggilbert "greggilbert (1 commits)")[![mul14](https://avatars.githubusercontent.com/u/113989?v=4)](https://github.com/mul14 "mul14 (1 commits)")[![niknetniko](https://avatars.githubusercontent.com/u/1756811?v=4)](https://github.com/niknetniko "niknetniko (1 commits)")[![sniper7kills](https://avatars.githubusercontent.com/u/5902574?v=4)](https://github.com/sniper7kills "sniper7kills (1 commits)")[![tflori](https://avatars.githubusercontent.com/u/4855611?v=4)](https://github.com/tflori "tflori (1 commits)")[![UnrulyNatives](https://avatars.githubusercontent.com/u/6769986?v=4)](https://github.com/UnrulyNatives "UnrulyNatives (1 commits)")

---

Tags

laravelauthaclrolespermissionsilluminate

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[geniusts/roles

Powerful package for handling roles and permissions in Laravel 6

6416.6k](/packages/geniusts-roles)

PHPackages © 2026

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