PHPackages                             balfour/laravel-custodian - 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. balfour/laravel-custodian

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

balfour/laravel-custodian
=========================

A super lightweight library for handling role based permissions in Laravel

0.0.1-alpha(6y ago)010MITPHPPHP >=7.2.0

Since Feb 24Pushed 2y ago6 watchersCompare

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

READMEChangelog (1)Dependencies (5)Versions (3)Used By (0)

laravel-custodian
=================

[](#laravel-custodian)

A super lightweight library for handling role based permissions in Laravel.

*This library is in early release and is pending unit tests.*

Table of Contents
-----------------

[](#table-of-contents)

- [Why](#why)
- [Installation](#installation)
- [Configuration](#configuration)
- [Configuring User Model](#configuring-user-model)
- [Usage](#usage)
    - [Creating Roles](#creating-roles)
    - [Registering Permissions](#registering-permissions)
    - [Listing Available Permissions](#listing-available-permissions)
    - [Assigning Permissions to Roles](#assigning-permissions-to-roles)
    - [Revoking Permissions from Roles](#revoking-permissions-from-roles)
    - [Assigning Roles to Users](#assigning-roles-to-users)
    - [Syncing User Roles](#syncing-user-roles)
    - [Revoking Roles from Users](#revoking-roles-from-users)
    - [Listing User Roles](#listing-user-roles)
    - [Retrieving a User's Permissions](#retrieving-a-users-permissions)
    - [Authorizing Users](#authorizing-users)

Why?
----

[](#why)

There are some great existing role based authorization libraries out there, so why another one?

For our internal systems, we wanted something which is:

1. simple to use
2. does not contain all the bells and whistles
3. works with the framework's existing authorization library
4. focuses on performance first
5. elegantly modeled without a plethora of pivot tables - json type works fine!

We've managed to keep things simple and efficient by:

1. creating just 2 tables, a `roles` table and a `role_user` table mapping users to roles
2. storing assigned permissions in a json column on the `roles` table
3. performing just a single database query to retrieve all users, assigned roles & permissions
4. keeping an in-object mapping cache of user -> permissions
5. decorating this mapping cache with an external cache of your choice (memcached, redis, etc)

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

[](#installation)

```
composer require balfour/laravel-custodian
```

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

[](#configuration)

The package works out the box without any configuration, however if you'd like to publish the config file, you can do so using:

`php artisan vendor:publish --provider="Balfour\LaravelCustodian\ServiceProvider"`

**Custom User Model**

The library will try to detect the path of your user model from the auth config's default guard.

If you'd like to use a custom model such as `\App\User::class`, you can specify a class path in the `user_model` config value.

An alternative way to set the user model on the fly is via the `Balfour\LaravelCustodian\UserModelResolver::setModel(\App\User::class)` function.

**Super Admins**

The `admins` config value takes an array of email addresses which should be given super admin access on the custodian. This means that these users will automatically pass all gate (permission) checks.

We **do not** recommend using this outside of testing. You should rather make use of Laravel's `Gate::before` or `Gate::after` hooks to accomplish this.

Configuring User Model
----------------------

[](#configuring-user-model)

Add the `HasRoles` trait to your user model.

```
namespace App;

use Balfour\LaravelCustodian\HasRoles;
use Illuminate\Notifications\Notifiable;
use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasRoles;
}
```

This will establish a relationship between users and roles; and also give you the following utility methods:

```
/**
 * @param mixed $role
 */
public function assignRole($role)

/**
 * @param mixed $role
 */
public function revokeRole($role)

/**
 * @param array $ids
 */
public function syncRoles(array $ids)
```

Usage
-----

[](#usage)

### Creating Roles

[](#creating-roles)

```
use Balfour\LaravelCustodian\Models\Role;

$admin = Role::create(['name' => 'admin']);

$support = Role::create(['name' => 'customer-support']);
```

### Registering Permissions

[](#registering-permissions)

You must register permissions before they can be assigned to roles.

The package does not store available permissions in the database, but instead, registers them against a `PermissionRegistrar`. This means that permissions must be registered upon bootstrap, such as in your app's `AppServiceProvider`, or a module/package's `ServiceProvider`.

```
use Balfour\LaravelCustodian\Custodian;

$custodian = app(Custodian::class);
$custodian->register('create-user');
$custodian->register('view-user');
$custodian->register('view-user-support-tickets');
```

### Listing Available Permissions

[](#listing-available-permissions)

```
use Balfour\LaravelCustodian\Custodian;

$custodian = app(Custodian::class);
$permissions = $custodian->getAvailablePermissions();

// you could use this to generate a permission matrix for a user, or display a checkbox list
// of permissions on an edit user type of page
```

### Assigning Permissions to Roles

[](#assigning-permissions-to-roles)

```
use Balfour\LaravelCustodian\Models\Role;

$admin = Role::where('name', 'admin')->first();
$admin->give('create-user');
$admin->give('view-user');
```

### Revoking Permissions from Roles

[](#revoking-permissions-from-roles)

```
use Balfour\LaravelCustodian\Models\Role;

$admin = Role::where('name', 'admin')->first();
$admin->revoke('create-user');
```

### Assigning Roles to Users

[](#assigning-roles-to-users)

```
use App\User;
use Balfour\LaravelCustodian\Models\Role;

$user = User::find(1);
$user->assignRole('admin');

// you can also assign using a model
$admin = Role::where('name', 'admin')->first();
$user->assignRole($admin);

// or by id
$user->assignRole(1);
```

### Syncing User Roles

[](#syncing-user-roles)

```
use App\User;

$user = User::find(1);
$user->syncRoles([
    1,
    2,
]);
```

### Revoking Roles from Users

[](#revoking-roles-from-users)

```
use App\User;
use Balfour\LaravelCustodian\Models\Role;

$user = User::find(1);
$user->revokeRole('admin');

// you can also revoke using a model
$admin = Role::where('name', 'admin')->first();
$user->revokeRole($admin);

// or by id
$user->revokeRole(1);
```

### Listing User Roles

[](#listing-user-roles)

```
use App\User;

$user = User::find(1);
$roles = $user->roles;
```

### Retrieving a User's Permissions

[](#retrieving-a-users-permissions)

```
use App\User;
use Balfour\LaravelCustodian\Custodian;

$custodian = app(Custodian::class);
$user = User::find(1);
$permissions = $custodian->getUserPermissions();
```

### Authorizing Users

[](#authorizing-users)

The library does not add any special functionality for checking if a user can perform a specific permission (or ability).

Please see the [Laravel Authorization documentation](https://laravel.com/docs/5.8/authorization#authorizing-actions-using-policies)for more info on this subject.

```
use App\User;

$user = User::find(1);
var_dump($user->can('create-user'));

// via middleware
Route::put('/users/{user}', function (User $user) {

})->middleware('can:view-user');

// via blade
@can('view-user)
    // ....
@endcan
```

###  Health Score

20

—

LowBetter than 14% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 62.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

Unknown

Total

1

Last Release

2269d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/054093c4138d9bea138f6226b632f8f7ad0adb516562480f7f77868d481e75f0?d=identicon)[balfourgroup](/maintainers/balfourgroup)

---

Top Contributors

[![matthewgoslett](https://avatars.githubusercontent.com/u/1571743?v=4)](https://github.com/matthewgoslett "matthewgoslett (5 commits)")[![Gcobani](https://avatars.githubusercontent.com/u/8480669?v=4)](https://github.com/Gcobani "Gcobani (3 commits)")

### Embed Badge

![Health badge](/badges/balfour-laravel-custodian/health.svg)

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

###  Alternatives

[tymon/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

11.5k49.1M350](/packages/tymon-jwt-auth)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k84.2M225](/packages/laravel-horizon)[php-open-source-saver/jwt-auth

JSON Web Token Authentication for Laravel and Lumen

8359.8M53](/packages/php-open-source-saver-jwt-auth)[illuminate/auth

The Illuminate Auth package.

9327.3M1.0k](/packages/illuminate-auth)[alajusticia/laravel-logins

Session management in Laravel apps, user notifications on new access, support for multiple separate remember tokens, IP geolocation, User-Agent parser

2011.0k](/packages/alajusticia-laravel-logins)

PHPackages © 2026

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