PHPackages mabrouk/permission-simple - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. mabrouk/permission-simple ActiveLibrary[Authentication & Authorization](/categories/authentication) mabrouk/permission-simple ========================= a laravel package to handle dealing with permissions in simple structure 10PHP Since Apr 23Pushed 4y ago1 watchersCompare [ Source](https://github.com/ah-mabrouk/permission-simple)[ Packagist](https://packagist.org/packages/mabrouk/permission-simple)[ RSS](/packages/mabrouk-permission-simple/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (1)DependenciesVersions (1)Used By (0) Mabrouk/Permission ================== [](#mabroukpermission) mabrouk/permission-simple is a Laravel api package for dealing with project admins permissions using Database approach. Table of Content ---------------- [](#table-of-content) [Important Introduction](#important-introduction) [Usage sequence](#usage-sequence) [Installation](#Installation) [Configurations according to project needs](#Configurations-according-to-project-needs) [Using `HasPermission` Trait on desired models](#Using-%60HasPermission%60-Trait-on-desired-models) [Out of the box methods and attributes](#Out-of-the-box-methods-and-attributes) - [Methods](#Methods) - [Attributes](#Attributes) [Out of the box models](#Out-of-the-box-models) [Out of the box routes](#Out-of-the-box-routes) [What else?](#What-else?) [Models Api Resources to expect in requests response](#Models-Api-Resources-to-expect-in-requests-response) [Any thing else?](#Any-thing-else?) [License](#License) Important introduction ---------------------- [](#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 -------------- [](#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 `php artisan permission:seed` 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 `permissions.php` config file. or guide frontend developer to this documentation [Models Api Resources to expect in requests response](#Models-Api-Resources-to-expect-in-requests-response) section Installation ------------ [](#installation) You can install the package using composer. ``` composer install mabrouk/permission-simple ``` In order to get things work, add the `PermissionOfficerMiddleware` at the end of the `$routeMiddleware` property of `app/Http/Kernel.php` class ``` protected $routeMiddleware = [ // ... 'permission-officer' => \Mabrouk\PermissionSimple\Http\Middleware\PermissionOfficerMiddleware::class, ]; ``` After this you may accept it on any specific grouped routes like `api` group under `$middlewareGroups` property in same `kernel` 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 `api` 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. ``` protected $middlewareGroups = [ 'api' => [ // ... 'permission-officer', ], ]; ``` - Now you need to run the following `command` in order to migrate package tables and publish `permissions.php` config file to config directory ``` php artisan permission:setup ``` Configurations according to project needs ----------------------------------------- [](#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 `config/permissions.php` > After modifying `permissions.php` config file don't forget to run below command: ``` php artisan config:cache ``` Using `HasPermission` Trait on desired models --------------------------------------------- [](#using-haspermission-trait-on-desired-models) Now you need to add `Mabrouk\PermissionSimple\Traits\HasPermission.php` 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 `permission.php` config file under the key `roleable_models` 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 ------------------------------------- [](#out-of-the-box-methods-and-attributes) After using `Mabrouk\PermissionSimple\Traits\HasPermission.php` trait on specified models in `permissions.php` 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 [](#methods) - `$user->roles()` 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 `$role->users()` the `users()` method here will have the same name as specified model key in `permissions.php` config file under `roleable_models` key. - `$user->permissions()` This is the relationship method and how to access permissions as a laravel normal relationship method. - `$user->subPermissions()` This is the relationship method and how to access sub-permissions as a laravel normal relationship method. - `$user->takeRole($role)` 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. - `$user->leaveRole($role)` You need to pass a role object to this method as the only one parameter it accepts in order to deassign role to the user. - `$user->canAccess($subPermissionName)` 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. - `$user->canAccess($subPermissionName)` 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. - `$user->leaveAllRoles()` This method don't accept any parameters and it just detach all roles related to the user. - `User::HasPermissions($permissionsIds)` 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 `->get()`, `->first()` 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 `permissions.php` config file after applying `Mabrouk\PermissionSimple\Traits\HasPermission.php` trait on it. ### Attributes [](#attributes) - `$user->roles` return a collection of a user assigned roles. - `$user->permissions` return a collection of a user assigned permissions. - `$user->subPermissions` return a collection of a user assigned sub-permissions. - `$user->SubPermissionsNames` return an array of a user assigned sub-permissions full names. Out of the box models --------------------- [](#out-of-the-box-models) We have 4 basic models to deal with: - `PermissionGroup` have full crud with translatable name - `Permission` ==> only index, show and update of translatable description and display name only. It depends on your project models names. - `SubPermission` with no separate crud functionality. usually it's one of (view, create, edit, delete). - `Role` have full crud with translatable name and description Out of the box routes --------------------- [](#out-of-the-box-routes) Let's run the `route:list` command and discover our package predefined routes ``` php artisan route:list ``` Actually we will find the output of the following routes in addition to your project current routes: ``` Route::apiResource('permission-groups', PermissionGroupController::class); Route::apiResource('permissions', PermissionController::class, ['except', ['store', 'destroy']]); Route::apiResource('roles', RoleController::class); ``` > Show, update and destroy routes accept model `id` as model segment in url > If above routes is not exists you may need to clear cached routes using command `php artisan route:clear` What else? ---------- [](#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 permissions.php config file. #### Note: [](#note) > You need to run below command after adding any new routes related to `base_urls` you specified in config file in order to add its suitable permissions. ``` php artisan permission:seed ``` > Now you will find that specified `project_full_permission_admins` 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 --------------------------------------------------- [](#models-api-resources-to-expect-in-requests-response) - PermissionGroupResource returned in all permission-groups requests except index ```