Download the PHP package thepublicgood/deadbolt without Composer
On this page you can find all versions of the php package thepublicgood/deadbolt. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download thepublicgood/deadbolt
More information about thepublicgood/deadbolt
Files in thepublicgood/deadbolt
Package deadbolt
Short Description Dead simple permissions for Laravel
License MIT
Informations about the package deadbolt
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 package.
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
Deadbolt can be installed via Composer:
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:
This will do two things...
- Create a new migration named
add_deadbolt_permissions_column
, - 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:
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:
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:
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
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
You can easily grab a list of permissions:
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:
You can also use the describe method to get the description for just one permission, or a sub-set of 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:
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.
The super()
method is really just a shortcut for give(Deadbolt::all())
:
If you attempt to assign a non-existent permission you'll get a NoSuchPermissionException
.
You can always get an array of permissions that are currently assigned to the user using the all
method:
Taking permissions away
You can take permissions away from a user with the revoke
method. It works in much the same way as give
:
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.
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:
Essentially, this is the same as doing revokeAll()->give($arrayOfPermissions)
.
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
Use the has
method to check if a user has ALL of the specified permissions:
any
Use the any
method to check if a user has ANY of the permissions specified:
none
Use the none
method to ensure that a user has NONE of the permissions specified:
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:
For testing permissions there are special set of methods specifically for testing across multiple users.
have
Use the have
method to test that all the users have the specified permissions:
dontHave
Use the dontHave
method to ensure that NONE of the users have the specified permissions:
any
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:
Now you have access to Deadbolt directly on the user model through the permissions()
method:
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 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.
A simple policy that uses Deadbolt could look something like this:
And you can test the policy with:
And if a policy needs to test for more than one permission:
Policies can be used to test abilities like this:
Drivers
Deadbolt is designed for simplicity, but sometimes you might need something just a little more flexible. Deadbolt uses a simple driver system for sourcing permissions, so it's easy to provide your own custom implementations. This can be handy if you really do want to store your permissions in your database, for example.
Deadbolt includes an ArrayDriver
by default that sources permissions from the default deadbolt.php
config file. If you want to write a custom driver you can do so by passing a new driver instance to the driver method before calling user()
:
It's annoying to call the driver
method every time you use Deadbolt, so you can set the custom driver in the config file:
Custom Drivers
If, for example, you need to source a list of permissions from your database, you can write your own driver. A custom driver class needs to implement Drivers\Contacts\DriverInterface
and the only requirement is to implement a permissions
method.
The permissions
method must return an array of permission names:
How the permissions
method sources permissions is up to you. It could a database request, or even a remote API request.
JavaScript Helper
Deadbolt includes a simple JavaScript helper that provides some simple tools for checking permissions. You'll need to pass the user permissions to your front-end. You can import the Deadbolt
class into your JavaScript component. If you're using Vue you could do something like this:
Upgrading from version 1
If you're upgrading Deadbolt from version that is already used on a project, then you should be able to simply replace Deadbolt 1 with Deadbolt 2. However, if you have used the "groups" feature Deadbolt 1 you will need to look at an alternative since groups are no longer available as of Deadbolt 2.
In addition, if you are using a custom Driver, the removal of groups will affect the method signatures. The original groups
method has been removed, and the permissions
method no longer takes any parameters.
Deadbolt 2 only supports PHP 7.3 and up, and Laravel 7.0 and up.