PHPackages                             thepublicgood/deadbolt - 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. thepublicgood/deadbolt

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

thepublicgood/deadbolt
======================

Dead simple permissions for Laravel

v3.0.0(2mo ago)166.2k2MITPHPPHP ^8.2CI passing

Since Feb 25Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/tpg/deadbolt)[ Packagist](https://packagist.org/packages/thepublicgood/deadbolt)[ RSS](/packages/thepublicgood-deadbolt/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (12)Versions (30)Used By (0)

[![Tests](https://github.com/tpg/deadbolt/actions/workflows/tests.yml/badge.svg)](https://github.com/tpg/deadbolt/actions/workflows/tests.yml)

Why another authorization package?
----------------------------------

[](#why-another-authorization-package)

There are plenty of authorization packages around. But I wanted something that was way simpler than what was on offer and something that I could use easily with my current stack which includes plenty of JavaScript. I've used many of the current top authorisation packages, and will likely use them in the future, but in some cases they're just a little over the top.

Deadbolt is "dead" simple. It's in the name. You define your permissions in the config file (just so you have some source of truth), and you can assign them to your users. The only required database change is a `permissions` column on your `users` table. No need for any additional migrations or complicated configurations.

Deadbolt is simple by design. If you need something more feature rich, there are plenty of other choices. If this doesn't fit the bill, then my go to package is Spatie's [laravel-permission](https://github.com/spatie/laravel-permission) package.

Requirements
------------

[](#requirements)

Version 3 requires PHP 8.1 or later and Laravel 10 or later. If you're still using older versions then you'll need to stick with version 2.2.

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

[](#installation)

Deadbolt can be installed via Composer:

```
composer require thepublicgood/deadbolt
```

Getting Started
---------------

[](#getting-started)

Deadbolt works by setting permissions in a JSON array in a column on your users table. So before you can use Deadbolt, you'll need to add that column. Deadbolt comes with a simple Artisan command that will do this for you:

```
php ./artisan deadbolt:install
```

This will do two things...

1. Create a new migration named `add_deadbolt_permissions_column`,
2. Place a copy of the Deadbolt config at `config/deadbolt.php`.

You can alter the migration if you need to, but the default will add a column named `permissions` to the `users` table.

You can now define your permissions in the `deadbolt.php` config file. That's it.

The `deadbolt:install` command is only available if the `deadbolt.php` file does not exist in the `config` directory. However, if you need to, you can always get the same result by running:

```
php ./artisan vendor:publish --provider=TPG\\Deadbolt\\DeadboltServiceProvider
```

Permissions
-----------

[](#permissions)

Permissions are defined in the `deadbolt.php` config file, in the appropriately named `$permissions` array. Permissions can be named anything you like, for example:

```
$permissions = [
	'Create Articles',
	'Edit Articles',
	'Delete Articles',
];
```

However, naming permissions this way could lead to errors later on. So Deadbolt provides a way to create simpler permissions names and provide a description for each permission:

```
$permissions = [
	'articles.create' => 'Create Articles',
	'articles.edit' => 'Edit Articles',
	'articles.delete' => 'Delete Articles',
];
```

The point of defining your permissions here is to create a single source of truth for your permissions. Assigning a permission to a user that does not exist in this array will throw an exception. Similarly, checking if a user has a permission that does not exist will also throw an exception.

Working with permissions
------------------------

[](#working-with-permissions)

### The `Deadbolt` facade

[](#the-deadbolt-facade)

Deadbolt provides a Laravel facade named `Deadbolt`. Anything that Deadbolt can do can be handled through the use of this facade.

### Getting the defined permissions

[](#getting-the-defined-permissions)

You can easily grab a list of permissions:

```
$permissions = Deadbolt::all();

/*
[
	'articles.create',
	'articles.edit',
	'articles.delete',
]
*/
```

This will return an array of permission names. If you also want the descriptions you defined for each permission, you can use the describe method:

```
$permissions = Deadbolt::describe();

/*
[
	'articles.create' => 'Create Articles',
	'articles.edit' => 'Edit Articles',
	'articles.delete' => 'Delete Articles',
]
*/
```

You can also use the describe method to get the description for just one permission, or a sub-set of permissions:

```
$permission = Deadbolt::describe('articles.create');
// $permission = 'Create Articles';

$permissions = Deadbolt::describe(['articles.create', 'articles.edit']);

/*
[
	'articles.create' => 'Create Articles',
	'articles.edit' => 'Edit Articles',
]
*/
```

### Assigning permissions

[](#assigning-permissions)

Deadbolt uses the word "User" to mean any model that has permissions that returns array of assigned permissions. This could be any Laravel model that has a "permissions" attribute, but it doesn't have to your actual `User` model. It could be `Role` model, or an `Organisation` model, for example.

To work with permissions on a "user" Deadbolt provides a `user()` method on the `Permissions` facade to which you need to pass your Laravel model:

```
$deadbolt = Deadbolt::user($request->user());
```

There are two main methods you can use to assign permissions. The `give()` method can be used to assign specific permissions, and the `super()` method is a quick way to assign ALL permissions.

```
// Give a single permission
Deadbolt::user($user)->give('articles.create');

// Give muliple permissions
Deadbolt::user($user)->give('articles.create', 'articles.edit');

// Give an array of permissions
Deadbolt::user($user)->give($arrayOfPermissions);
```

The `super()` method is really just a shortcut for `give(Deadbolt::all())`:

```
Deadbolt::user($user)->super();
```

If you attempt to assign a non-existent permission you'll get a `NoSuchPermissionException`.

```
Deadbolt::user($user)->give('articles.publish');
// Throws a NoSuchPermissionException.
```

You can always get an array of permissions that are currently assigned to the user using the `all` method:

```
$permissions = Deadbolt::user($user)->all();
```

### Taking permissions away

[](#taking-permissions-away)

You can take permissions away from a user with the `revoke` method. It works in much the same way as `give`:

```
// Revoke a single permission
Deadbolt::user($user)->revoke('articles.edit');

// Revoke multiple permissions
Deadbolt::user($user)->revoke('articles.edit', 'articles.delete');

// Revoke an array of permissions
Deadbolt::user($user)->revoke($arrayOfArticles);
```

Again, trying to revoke a permission that is not defined will throw a `NoSuchPermissionException`, however attempting to a permission DOES exist but not assigned to the user, the `revoke` method will do nothing.

In addition there is also a `revokeAll` method which is simply remove all permissions currently assigned to the user.

```
Deadbolt::user($user)->revokeAll();
```

### Syncing permissions

[](#syncing-permissions)

Sometimes it can be useful to synchronise a users permissions. You can do this with the `sync` method, which will revoke permissions NOT in the passed array and assign permissions that are not already assigned:

```
Deadbolt::user($user)->sync($arrayOfPermissions);
```

Essentially, this is the same as doing `revokeAll()->give($arrayOfPermissions)`.

Testing for permissions
-----------------------

[](#testing-for-permissions)

Now that you have users with permissions, you need to be able to test for those permissions. Deadbolt provides a simple set of methods for this.

### has

[](#has)

Use the `has` method to check if a user has *ALL* of the specified permissions:

```
// Check if a user has a permission
Deadbolt::user($user)->has('articles.create');

// Check that a user has ALL of the permissions
Deadbolt::user($user)->has('articles.create', 'articles.edit');
```

### any

[](#any)

Use the `any` method to check if a user has ANY of the permissions specified:

```
// Will be true even if only one of the permissions is assigned.
Deadbolt::user($user)->any('articles.edit', 'articles.delete');
```

### none

[](#none)

Use the `none` method to ensure that a user has NONE of the permissions specified:

```
// Will be false if the user has any of the specified permissions
Deadbolt::user($user)->none('articles.create', 'articles.delete');
```

Multiple users
--------------

[](#multiple-users)

Deadbolt also allows you to deal with permissions across multiple users at the same time. By using the `users` method on the `Deadbolt` facade, you can use the same set of methods to work with more than one user at a time by passing a collection of user models:

```
// Give all the users a permission
Deadbolt::users($users)->give('articles.edit');

// Remove the specified permisssions from all users.
Deadbolt::users($users)->revoke('articles.delete');
```

For testing permissions there are special set of methods specifically for testing across multiple users.

### have

[](#have)

Use the `have` method to test that all the users have the specified permissions:

```
// All the users MUST HAVE all of the permissions
Deadbolt::users($users)->have($arrayOfPermissions);
```

### dontHave

[](#donthave)

Use the `dontHave` method to ensure that NONE of the users have the specified permissions:

```
Deadbolt::users($users)->dontHave($arrayOfPermissions);
```

### any

[](#any-1)

The `HasPermissions` Trait
--------------------------

[](#the-haspermissions-trait)

Deadbolt also comes with a simple `HasPermissions` trait which you can add to your `User` model (or whichever model is given permissions. It works by simply doing the `Deadbolt::user($user)` part for you. To get started, simply add the `HasPermissions` trait to your model:

```
class User extends Authenticatable
{
    use HasPermissions;

    //...
}
```

Now you have access to Deadbolt directly on the user model through the `permissions()` method:

```
$user = User::find(1);

// Give a permission
$user->permissions()->give('articles.edit');

// Or revoke a permission
$user->permissions()->revoke('articles.edit');

// Or test for a permission
$canEdit = $user->permissions()->has('articles.edit');
```

The `HasPermissions` trait is optional and there is no requirement for you to use it instead of using the `Deadbolt` facade directly. Either way is correct and you can choose whichever feels better.

Laravel Policies
----------------

[](#laravel-policies)

Laravel policies are a great way to deal with user abilities associated with your different models, and Deadbolt works perfectly with Laravel policies. You can read the Laravel documentation about policies [here](https://laravel.com/docs/authorization#creating-policies).

A simple policy that uses Deadbolt could look something like this:

```