Download the PHP package back2lobby/access-control without Composer

AccessControl is a Laravel package for easy role & permission management with model-based role assignment and role-based permissions.

Table of Contents

Introduction

AccessControl simplifies role & permission management by enabling the assignment of roles based on models and defining role-based permissions for fine-grained control over user access.

Once installed, you can simply tell the access-control what you want to allow at the gate:

Installation

Note: AccessControl requires PHP 8.1+ and Laravel 9.0+

1. Install AccessControl with composer:

2. Use the HasRoles in the User Model:

   If you want to use custom user model instead of App\Models\User, head over to Custom User Model section.

3. If you have a roleable model, then add AccessControl's trait to your roleable model:

4. Now, to run AccessControl's migrations. First publish the migrations into your app's migrations directory, by running the following command:

5. Finally, run the migrations:

Once it's installed, you can use a seeder to create base roles and permissions for your Laravel application. For example:

Facade

Whenever you use the AccessControl facade in your code, remember to add this line to your namespace imports at the top of the file:

If your IDE is facing any issues with this facade, please use barryvdh/laravel-ide-helper

Terminologies

Role:

A set of permissions that can be assigned to a user.

Permission:

A right to perform a specific action or access a specific resource.

Direct permission:

A permission that is allowed or forbidden directly to a role.

Indirect permission:

A permission that a user has because of a super permission it has, rather than being directly allowed or forbidden.

Super permission:

A permission that is used to grant all permissions, except for those that are forbidden directly.

Direct Role

A role is a direct role for a permission if it is allowed for the permission directly.

Indirect Role

A role is an indirect role for a permission, if it is not allowed for the permission directly rather the role have that permission because it has super permission.

Usage

Role

Creating Role

Role can be created using createRole method. Example:

You can specify roleables also, which will restrict the role to be assigned for the given roleable. Example:

Multiple roles can be created at once like this:

Updating Role

Role can be updated using updateRole method. Example:

Deleting Role

Role can be deleted using deleteRole method. Example:

Getting Role

To retrieve a role, you can use the method getRole. Example:

To retrieve all the roles available we can do something like to get a Collection of available roles.

Allowing Permissions

To allow a role for a specific permission, you can use the method allow and then chain it with method to. Example:

Alternatively, we can use allow method from Role Model itself like:

To allow all the permissions available indirectly (except forbidden specifically), use method superPermission like this:

The method superPermission needs the permission named *. It will create it in case it's not available.

Disallowing Permissions

Take back a permission from a user with method disallow and chain it with method to. Example:

Alternatively, we can use disallow from Role Model itself like:

To take back the super permission given to the role, use method superPermission() like this:

Forbidding Permissions

Forbid a permission for the role using method forbid and chain it with method to. Example:

Alternatively, we can use forbid from Role Model itself like:

You can forbid the role from all the permissions indirectly (except allowed specifically) using the method superPermission() like this:

Getting Permissions For Role

To get all the permissions a role have including allowed and forbidden, we can use method getAllPermissionsOf like:

To get only specific type of permissions for the role, we can use methods getAllowedPermissionsOf, getDirectlyAllowedPermissionsOf, getIndirectlyAllowedPermissionsOf, getForbiddenPermissionsOf, getDirectlyForbiddenPermissionsOf, getIndirectlyForbiddenPermissionsOf. Examples:

Read Terminologies if you don't know about direct/indirect permissions.

Assigning Role

Role can be assigned to any user using method assign and chain it with to method. Alternatively, you can use the assign method that's available method on the User model itself. Example:

You can also specify the roleable if the role requires specific roleables like this. For example, you want a user to be manager for a specific project only. It can be achieved like this:

Retracting Role

Assigned role can be retracted from any user using method retract and chain it with from method. Example:

You can also specify the roleable to retract role only for the specific roleable. For example, if a user is the manager of multiple companies, the manager role for only given company will be retracted from the user:

Checking Role

To check if a user have a specific role use method is and chain it with a or an methods. Example:

To check if a user have a specific role chain it with notA or notAn methods. Example:

To check if user have all the given roles, we can do something like:

It doesn't check for any roleables even if the role is restricted to some roleables. For Example, It will return true if the user have manager role for any roleable:

To check if user have any of the given roles, we can do something like:

Resetting Role

To remove all the permissions from a role, we can reset it using the method resetRole method. Example:

Permission

Creating Permission

Permission can be created using the method createPermission method. Example:

Multiple permissions can be created at once using the method createManyPermissions like this:

Updating Permission

Permission can be updated using the method updatePermission. For example, to change a permission's name from remove-post to delete-post we can do something like:

Deleting Permission

To delete a permission we can use the method deletePermission like:

Getting Permission

To retrieve a permission we can use the method getPermission like:

To retrieve all the permissions available, use the method getPermissions. Example:

Getting Roles Having Permission

To get all the roles that have a permission, we can use method getAllRolesOf like:

To get only specific type of roles for the permission, we can use methods getAllowedRolesOf, getDirectlyAllowedRolesOf, getIndirectlyAllowedRolesOf, getForbiddenRolesOf, getDirectlyForbiddenRolesOf, getIndirectlyForbiddenRolesOf. Examples:

Read Terminologies if you don't know about direct/indirect roles.

User

Getting User Roles

To get all the roles assigned to a user, we can use the method roles provided by Back2Lobby\AccessControl\Models\User. Example:

Getting User Permissions

To get all the permissions allowed for user through various roles, we can use the method permissions provided by Back2Lobby\AccessControl\Models\User. Example:

Getting Users With Specific Role

To get all the users that have a specific role, we can use the static method whereIs provided by Back2Lobby\AccessControl\Models\User. Example:

If the target role is restricted to some roleables, we can do something like:

You can also reverse the logic by using users method from the role model instead:

Getting Users With Specific Permission

To get all the users that have a specific permission, we can use the static method whereHas provided by Back2Lobby\AccessControl\Models\User. Example:

Checking User Permission

To check if a user have specific permission from any role, we can use the method canUser and chain it with method do like this:

You can also specify roleables like this:

Resetting User

To remove all the roles from a user, we can use the method resetUser. Example:

Features

Cache

All roles and permissions are cached and refreshed automatically every 24 hours. This optimization improves performance and reduces unnecessary database queries. Note that user data is not cached as it can frequently change.

You can manually sync all the roles and permissions with database with sync method. For example:

To clear the cache you can use the method clearCache like:

Even after clearing cache the local store will still have the roles and permissions, you can remove them also using the method reset: Example:

Manually caching the store can be achieved using cache like:

Note: By default, file is used as the cache driver, but it can be changed in access.php config file.

Authorization

To check roles and permissions in blade files, we can use Laravel built in can method on the user model. For Example:

If you want to check permission for a specific model, then we can do something like:

Blade Directive

Similarly, to check roles and permissions in blade files, we can use Laravel built in @can directive to check. For Example:

Config File

Access Control provides a configuration file that can be used to configure the behaviour of the package including specifying cache driver and custom user model.

You can publish the config file access.php using the command:

Middleware

Similarly, built in can middleware from Laravel as:

This will check if the authenticated user has the access-dashboard permission before processing the request.

You can also use the can middleware to check permissions for a specific model instance. For example, the route below will only be processed for users who have the edit-post permission on the Post model instance that is passed to route model binding in /posts/{post}/edit.

In this case, Post::class is passed to specify the model class for which the permission check should be performed. Note that this will only work if the route has route model binding for the Post model.

Custom User Model

By default, App\Models\User model is used for authorization and authentication for this package. To use custom model instead, following steps are needed:

• Specify the model in access.php. For Example,

• Make sure your custom user model extends Illuminate\Foundation\Auth\User.

• Migrate the database tables related to the package or just use this command to get a fresh database.

• Note: Make sure you have specified the new auth model for the guard in auth.php config file. For Example,