Download the PHP package coucounco/laravel-acl without Composer

Laravel-Acl

This is a package that provide Access Control List for Laravel 6.0|7.0|8.0|9.0.

For Laravel 6.0|7.0|8.0 use v1.

For Laravel 9.0 use v2.

Getting started

This package can be installed through Composer:

After installation you must perform these steps:

1) Add the service provider in config/app.php file:

2) Publish the laravel-acl config in your app

This step will copy config files in the config folder of your Laravel App.

• config/acl.php
• congig/acl/users.php

When it is published you can manage the configuration of larvel-acl through the file in config/acl.php, it contains:

3) Configure acls

laravel-acl provide acls and permissions not only to one model (default App\Models\User) but you can configure many. By default, the acls users that is using the model App\Models\User is used. But you can add more acls if needed.

Exemple :

Each acls have a config file associated. users has config/acl/users.php and contains the following :

3) Configure ACL for users

Optionally, you can enable direct acl on User

To enable this feature, you have to edit model.user.enableAcl it in the config/acl/users.php file and do the following instructions.

If you don't want direct acl on user, you can jump to the next chapter.

3.1) Update the User model

Add the UserAcl trait in your User model.

3.2) Add the acl column in the users table

Create a new migration file to update the users table

And add the new column

By default the name of this column is acl, but you can change it by updating model.user.attributeName in the config/acl/users.php file and in this migration file.

4) Configure ACL for groups

Optionnaly you can enable group acl.

To enable this feature, you have to edit model.user.enableAcl it in the config/acl/users.php file and do the following instructions.

If you don't want direct acl on user, you can jump to the next chapter.

4.1) Set up database tables

To enable the acl for groups, you have to create some more tables or to update your existing tables.

You need a groups table and the pivot table group_user to create the ManyToMany relation. (it's okay if you have different naming)

If you need to create these tables please follow the chapter 4.1.1 else follow the 4.1.2

4.1.1) Create tables

Do not create these tables if you already have similar grouping table with a ManyToMany relation to User.

Create a new migration file to create the groups table

with the following content :

The name of the acl column can be changed by updating model.group.attributeName in the config/acl/users.php file and in this migration file.

Add a new migration file to create the pivot table named group_user

with the following content :

That's all for database table creation.

4.1.2) Update tables

Add the acl column in your grouping table.

Create a new migration file to update your grouping table.

Be sure to have the right name for the table.

And add the new column

By default the name of this column is acl, but you can change it by updating model.group.attributeName in the config/acl/users.php file and in this migration file.

That's all for database table update.

4.2) Update the group model

Add the GroupAcl trait in your Group model. You also need to add the relationship to the User model

4.3) Update the User model

Add the relation into the User model.

If your group table has a different name, it's not a problem. You just have to update model.group.relationship and set this name on the relation function in the the config/acl/users.php file

5) Enjoy !

Everthing is ready, now jump to the documentation section to learn more about laravel-acl.

Documentation

This chapter explain how laravel-acl works and describe the available tools (helpers, middleware, ...).

Define permissions and roles

Permission and roles are managed in a hard coded way in the config/acl/users.php file. This choice was made to simplify the use and to avoid database query as much as possible.

Permissions

You can easly add permissions by adding a new entry in the permissions array in the config/acl/users.php file.

The key is the name of the permission and the value is the identifier

It's mandatory to have the superadmin permission with the identifier set as 0.

You can manage every other permissions the way you want.

Roles

A role is a preset of permissions. You can manage roles with the roles array in the config/acl/users.php file.

The key is the name of the role and the value is the ACL.

ACL

What is the ACL ?

It's a string value that define the permissions of a user or a group.

This value is stored by default in the acl column in the users table and in the group table.

Let's take the following ACL as a exemple.

If we have defined the following permissions.

ACL are red from the right to the left.

What does each digit means ?

• The first digit "0" of the ACL "1000003410" represent the permission with the 0 identifier. In our case it's the superadmin permissions.
• The 2nd digit "1" represent the permission with the 1 identifier. (it's the user permission).
• The 4th digit "3" represent the page permission.
• The 8th "0" represent the run_page_export permission.
• The last digit (the 9th) "1" represent the run_page_import permission.

But, what are those values "0", "1", "2", "3", "4" on each digit ?

These values define the access level for the given permission

So, to describe the ACL "1000003410", the user has the following permissions/restrictions :

• The user is not a superadmin;
• The user has the read access on the user permission;
• The user has the delete acces on the group permission;
• The user has the update access on the page permission;
• The user can't perform run_page_export;
• And the user is allowed to perform run_page_import.

You know everything about the permissions, roles and ACL. Jump to the next chapter to learn how to grant and revoke permissions

Grant and revoke permissions

To a User

How to give the superadmin permission to a user :

If you don't save, the permission will not persist in the database.

How to give the read access to the group permission to a user :

How to give the delete access to the page permission to a user :

How to grant many permissions at once :

How to revoke a permission :

or you can also grant the ACL_NONE or ACL_DENY level.

How to revoke many permissions:

How to revoke all permissions:

To a group

It works the same way as with the user.

Now that you know how to grant and revoke permissions to a user or a group, you need to learn how to check permissions for a user.

Checking access

This chapter describe every way to check if a user has the permissions to acces pages or perform actions.

Gate

You can use Gate facade provided by laravel.

User model

You can use the Laravel can method of the User to check a permission.

Check if the user can read page :

It will return true if the user is able to read pages else it return false.

Check if the user can edit user in the context of the given group :

It will return true only if the user has the acces granted by the given group else it return false.

It's usefull to manage access to entity that are in relation with a specific group.

Check if the user can update the page in the context of many groups :

The 2nd parameter (groups)" must be a collection Illuminate\Support\Collection.

Middleware

You can use the acl middleware provided by laravel-acl to protect routes or a whole resource directly in the route files (routes/web.php).

Restrict the access to user with a given permission and level

This route will allow the acces only to user who have the user permission with the ACL_READ level.

Restrict the access to user with any of the given permission and level

This route will allow the acces only to user who have the user permission with the ACL_READ level or the group permission with the ACL_READ level.

Blade

It's usefull to be able to hide some buttons in your blade view. To achieve this, you can use some directive provided by Laravel.

The @can blade directive

It's the same as writing

The @cannot blade directive

The @canany blade directive

Helper

Checking permissions

Checking if the user can read page

Retrieve permissions and roles

You can retrieve all permissions with the helper method :

Get permissions for another acls, just pass the acls name in parameter acl_permissions('members')

You can retrieve all roles with the helper method :

Get roles for another acls, just pass the acls name in parameter acl_permissions('members')

The strict option

Sometimes, you will probably want to check if the user have strictly a permission.

What does this mean ?

Exemple:

• $user1 have the superadmin permission
• $user2 have the is_manager permission

So when you check if the $user1 have the is_manager permission :

this will return true even if he don't have the is_manager permission because he is superadmin.

It's possible to check permissions with the strict parameter.

this will return false even if the user is superadmin.

this will return true because $user2 have the is_manager permission.