Download the PHP package mabrouk/permission without Composer

Mabrouk/Permission

mabrouk/permission is a Laravel api package for dealing with project admins permissions using Database approach.

Table of Content

Important Introduction

Usage sequence

Installation

Configurations according to project needs

Using HasPermission Trait on desired models

Out of the box methods and attributes

• Methods
• Attributes

Out of the box models

Out of the box routes

What else?

Models Api Resources to expect in requests response

Any thing else?

License

Important introduction

In order to get the most benefit of this package results, try to follow the standard routes naming to have a well organized permissions names suites very well with your models naming as well.

• avoid using verbs in routes naming such as get_users and get_news, instead use the model plural name will fit very well here trust me.

Usage sequence

After installation and modifing configuration:

• add new routes -if you don't have some- which have one of the basic urls in config file
• run command when you need to apply permissions on newly added routes.
• include predefined routes which control permission groups, Roles, and permission display names in your api documentation to make it available for implementation from frontend developer working on admin-panel or any dashboard you specified its api base url in config file. or guide frontend developer to this documentation Models Api Resources to expect in requests response section

Installation

You can install the package using composer.

In order to get things work, add the at the end of the property of class

After this you may accept it on any specific grouped routes like group under property in same file or use it on specific routes in your routes file as most of middlewares you used to use before.

The first option to apply it to group for example will be more comfortable during development process as you will not have to think about it anymore after configuring package configuration with your project needs.

• Now you need to run the following in order to publish package migrations and publish config file to config directory

• Then you need to run the following in order to migrate package tables

Configurations according to project needs

Config file have several configuration options and already have enough comments to describe every key meaning and how to use.

You may access it under

After modifying config file don't forget to run below command:

Using HasPermission Trait on desired models

Now you need to add trait on models which will have roles such as "User" model for example. Don't forget to add this trait to all models you specified in config file under the key and don't forget to carefully read the instructions included in config file.

• You are all done with installation and structure. Now we need just to understand how to use it.

Out of the box methods and attributes

After using trait on specified models in config file as mentioned above you will have additional methods and attributes on specified models. let's take User model as example and see methods usage such as the following:

Methods

• This is the relationship method and how to access roles as a laravel normal relationship method. Put in mind that it's a polymorphic relationship so to get reversed relation the method here will have the same name as specified model key in config file under key.

• This is the relationship method and how to access permissions as a laravel normal relationship method.

• This is the relationship method and how to access sub-permissions as a laravel normal relationship method.

• You need to pass a role object to this method as the only one parameter it accepts in order to assign role to the user.

• You need to pass a role object to this method as the only one parameter it accepts in order to deassign role from the user.

• You need to pass a sub-permission name to this method as the only one parameter it accepts in order to check if the user have this specific sub-permission.

• This method don't accept any parameters and it just detach all roles related to the user.

• This is a query scope method in order to filter users whom have specific permissions and you can fetch the result as usual as using , or any other method as used to use.

note here that User model is used just as example and you can use the same functionality with any specified models in config file after applying trait on it.

Attributes

• return a collection of a user assigned roles.

• return a collection of a user assigned permissions.

• return a collection of a user assigned sub-permissions.

• return an array of a user assigned sub-permissions full names.

Out of the box models

We have 4 basic models to deal with:

• have full crud with translatable name
• ==> only index, show and update of translatable description and display name only. It depends on your project models names.
• with no separate crud functionality. usually it's one of (view, create, edit, delete).
• have full crud with translatable name and description

Out of the box routes

Let's run the command and discover our package predefined routes

Actually we will find the output of the following routes in addition to your project current routes:

Show, update and destroy routes accept model as model segment in url

If above routes is not exists you may need to clear cached routes using command

What else?

You are one step away from handling your project permissions with only running below command after adding any additional routes under specified base urls defined in config file.

Note:

You need to run below command after adding or modifying any routes related to you specified in config file in order to add or modify its suitable permissions.

Now you will find that specified in config file have full permissions.

Sub Permissions will be added depending on your routes available actions. For example if you specified actions of api resource route to allow just store and destroy for example it will affect added sub permissions accordingly, otherwise it will add the 4 actions to super admin user to play with it according to specific role he is modifying.

Models Api Resources to expect in requests response

• PermissionGroupResource returned in all permission-groups requests except index

• PermissionGroupSimpleResource returned in permission-groups index request

• PermissionResource

• SubPermissionResource

• RoleResource ==> Used in role crud except index

• RoleSimpleResource ==> used in roles index only

Any thing else?

Actually one more thing to know is that this package depend on mabrouk/translatable package in order to handle translation dynamically for any chosen language.

You will need to pass additional input "locale" in update requests of mentioned models and need to create roles and permission groups with your application default language. To get role/permission/permission group name or description with desired language you need to pass additional header to your requests "X-locale"

Both "locale" and "X-locale" accept values like ['en', 'ar', 'fr', ...] etc depending on languages you support in your project.

License

Mabrouk/Permission package is open-sourced software licensed under the MIT license.