Download the PHP package dubroquin/bouncer without Composer
On this page you can find all versions of the php package dubroquin/bouncer. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download dubroquin/bouncer
More information about dubroquin/bouncer
Files in dubroquin/bouncer
Informations about the package bouncer
Bouncer
This package adds a bouncer at Laravel's access gate.
Note: If you are upgrading from an earlier version of Bouncer, be sure to checkout the upgrade guide.
- Introduction
- Installation
- Facade
- Enabling cache
- Upgrade
- Upgrading to 1.0
- Usage
- Creating roles and abilities
- Assigning roles to a user
- Giving a user an ability directly
- Restricting an ability to a model
- Retracting a role from a user
- Removing an ability
- Checking a user's roles
- Getting all abilities for a user
- Authorizing users
- Blade directives
- Refreshing the cache
- Cheat sheet
- Alternative
- License
Introduction
Bouncer provides a mechanism to handle roles and abilities in Laravel's ACL. With an expressive and fluent syntax, it stays out of your way as much as possible: use it when you want, ignore it when you don't.
For a quick, glanceable list of Bouncer's features, check out the cheat sheet.
Bouncer works well with other abilities you have hard-coded in your own app. Your code always takes precedence: if your code allows an action, the bouncer will not interfere.
Once installed, you can simply tell the bouncer what you want to allow at the gate:
When you check abilities at the gate, the bouncer will be consulted first. If he sees an ability that has been granted to the current user (whether directly, or through a role) he'll authorize the check.
Installation
Simply install the bouncer package with composer:
Once the composer installation completes, you can add the service provider and alias the facade. Open config/app.php
, and make the following changes:
1) Add a new item to the providers
array:
2) Add a new item to the aliases
array:
This part is optional. If you don't want to use the facade, you can skip step 2.
3) Add the bouncer's trait to your user model:
4) Now, to run the bouncer's migrations, first publish the package's migrations into your app's migrations
directory, by running the following command:
5) Finally, run the migrations:
Facade
Whenever you use the Bouncer
facade in your code, remember to add this line to your namespace imports at the top of the file:
For more information about Laravel Facades, refer to the Laravel documentation.
Enabling cache
All queries executed by the bouncer are cached for the current request. For better performance, you may want to use cross-request caching. To enable cross-request caching, add this to your AppServiceProvider
's boot
method:
Warning: if you enable cross-request caching, you are responsible to refresh the cache whenever you make changes to user's abilities/roles. For how to refresh the cache, read refreshing the cache.
Upgrade
Upgrading to 1.0
The table structure in Bouncer 1.0 has changed significantly. To upgrade, you'll have to update your database schema to the new structure.
If your app has not made it to production yet and you can still rollback your migrations, do that. Once you've rolled back all migrations, you can delete the Bouncer migration file and republish it to get the newer version:
For apps that are in production and already have real data in the database, Bouncer ships with an upgrade migration file which will migrate your schema and your data to the new structure.
Remember: Before migrating, be sure to run a full backup of your database! If anything goes wrong, you'll want to be able to restore from your backup.
After updating to Bouncer 1.0 through composer, run the following command:
This will create a new migration file under database/migrations
, and will automatically call artisan's migrate
command to migrate the database.
Congratulations, you're done with your upgrade!
If you have previously changed Bouncer's default table names, you will have to change them in this migration file. To prevent the bouncer:upgrade
command from actually migrating your database, call it with the no-migrate
flag:
This will create the migration file, but will not actually migrate the database. You can now manually edit the migration file to make any changes you need. After you've made the necessary changes, remember to run the php artisan migrate
command yourself.
Usage
Adding roles and abilities to users is made extremely easy. You do not have to create a role or an ability in advance. Simply pass the name of the role/ability, and Bouncer will create it if it doesn't exist.
Note: the examples below all use the
Bouncer
facade. If you don't like facades, you can instead inject an instance ofDubroquin\Bouncer\Bouncer
into your class.
Creating roles and abilities
Let's create a role called admin
and give it the ability to ban-users
from our site:
That's it. Behind the scenes, Bouncer will create both a Role
model and an Ability
model for you.
Assigning roles to a user
To now give the admin
role to a user, simply tell the bouncer that the given user should be assigned the admin role:
Alternatively, you can call the assign
method directly on the user:
Giving a user an ability directly
Sometimes you might want to give a user an ability directly, without using a role:
Here too you can accomplish the same directly off of the user:
Restricting an ability to a model
Sometimes you might want to restrict an ability to a specific model type. Simply pass the model name as a second argument:
If you want to restrict the ability to a specific model instance, pass in the actual model instead:
Retracting a role from a user
The bouncer can also retract a previously-assigned role from a user:
Or do it directly on the user:
Removing an ability
The bouncer can also remove an ability previously granted to a user:
Or directly on the user:
Note: if the user has a role that allows them to
ban-users
they will still have that ability. To disallow it, either remove the ability from the role or retract the role from the user.
If the ability has been granted through a role, tell the bouncer to remove the ability from the role instead:
To remove an ability for a specific model type, pass in its name as a second argument:
Warning: if the user has an ability to
delete
a specific$post
instance, the code above will not remove that ability. You will have to remove the ability separately - by passing in the actual$post
as a second argument - as shown below.
To remove an ability for a specific model instance, pass in the actual model instead:
Checking a user's roles
Note: Generally speaking, you should not have a need to check roles directly. It is better to allow a role certain abilities, then check for those abilities instead. If what you need is very general, you can create very broad abilities. For example, an
access-dashboard
ability is always better than checking foradmin
oreditor
roles directly. For the rare occasion that you do want to check a role, that functionality is available here.
The bouncer can check if a user has a specific role:
If the role you're checking starts with a vowel, you might want to use the an
alias method:
For the inverse, you can also check if a user doesn't have a specific role:
You can check if a user has one of many roles:
You can also check if the user has all of the given roles:
You can also check if a user has none of the given roles:
These checks can also be done directly on the user:
Getting all abilities for a user
You can get all abilities for a user directly from the user model:
This will return a collection of the user's abilities, including any abilities granted to the user through their roles.
Authorizing users
Authorizing users is handled directly at Laravel's Gate
, or on the user model ($user->can($ability)
).
For convenience, the bouncer class provides two passthrough methods:
These call directly into the Gate
class.
Blade directives
Bouncer does not add its own blade directives. Since Bouncer works directly with Laravel's gate, simply use its @can
directive to check for the current user's abilities:
Since checking for roles directly is generally not recommended, Bouncer does not ship with a separate directive for that. If you still insist on checking for roles, you can do so using the general @if
directive:
Refreshing the cache
All queries executed by the bouncer are cached for the current request. If you enable cross-request caching, the cache will persist across different requests.
Whenever you need, you can fully refresh the bouncer's cache:
Note: fully refreshing the cache for all users uses cache tags if they're available. Not all cache drivers support this. Refer to Laravel's documentation to see if your driver supports cache tags. If your driver does not support cache tags, calling
refresh
might be a little slow, depending on the amount of users in your system.
Alternatively, you can refresh the cache only for a specific user:
Cheat Sheet
Some of this functionality is also available directly on the user model:
Alternative
Among the bajillion packages that Spatie has so graciously bestowed upon the community, you'll find the excellent laravel-permission package. Like Bouncer, it nicely integrates with Laravel's built-in gate and permission checks, but has a different set of design choices when it comes to syntax, DB structure & features. Povilas Korop did an excellent job comparing the two in an article on Laravel News.
License
Bouncer is open-sourced software licensed under the MIT license
All versions of bouncer with dependencies
illuminate/container Version 5.1.20 - 5.4
illuminate/contracts Version 5.1.20 - 5.4
illuminate/database Version 5.1.20 - 5.4