{"id":17170304,"url":"https://github.com/nahid/permit","last_synced_at":"2025-04-04T12:06:41.214Z","repository":{"id":46571914,"uuid":"92187792","full_name":"nahid/permit","owner":"nahid","description":"A laravel package to handle user authorization and ACL","archived":false,"fork":false,"pushed_at":"2024-12-25T05:03:07.000Z","size":102,"stargazers_count":73,"open_issues_count":2,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T11:06:56.580Z","etag":null,"topics":["accessibility","acl","authorization","laravel","permissions","user-roles"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nahid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-23T15:16:20.000Z","updated_at":"2025-02-06T04:41:56.000Z","dependencies_parsed_at":"2024-10-31T16:04:36.439Z","dependency_job_id":"fdafb533-ee96-4e67-bb0e-4b3ffd91abaa","html_url":"https://github.com/nahid/permit","commit_stats":{"total_commits":63,"total_committers":4,"mean_commits":15.75,"dds":"0.15873015873015872","last_synced_commit":"1d0e459c45c1ee81350fcdd2dd49c9e126a37309"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpermit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpermit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpermit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpermit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nahid","download_url":"https://codeload.github.com/nahid/permit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174407,"owners_count":20896076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","acl","authorization","laravel","permissions","user-roles"],"created_at":"2024-10-14T23:29:30.080Z","updated_at":"2025-04-04T12:06:41.196Z","avatar_url":"https://github.com/nahid.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Permit\n\nLaravel Permit is an authorization and ACL package for laravel. Its fast and more customizable.\nYou can easily handle role based ACL or specific user wise permission. So, Lets start a journey with Laravel Permit.\n\n## Installation\n\nYou can start it from composer. Go to your terminal and run this command from your project root directory.\n\n```shell\ncomposer require nahid/permit\n```\n\nWait for a while, its download all dependencies.\n\n## Configurations\n\nAfter complete installation then you have to configure it. First copy these line paste it in `config/app.php` where `providers` array are exists.\n\n```php\nNahid\\Permit\\PermitServiceProvider::class,\n```\n\nand add the line for facade support\n\n```php\n'Permit'    =\u003e Nahid\\Permit\\Facades\\Permit::class,\n```\n\nhmm, Now you have to run this command to publish necessary files.\n\n```shell\nphp artisan vendor:publish --provider=\"Nahid\\Permit\\PermitServiceProvider\"\n```\n\nand then go to `config/permit.php` and edit with your desire credentials.\n\n```php\n\nreturn [\n    'users' =\u003e [\n        'model' =\u003e \\App\\Models\\User::class,\n        'table' =\u003e 'users',\n        'role_column'   =\u003e 'type'\n    ],\n\n    'super_user'    =\u003e  'admin',\n\n    'abilities'   =\u003e [\n       // \"module\"  =\u003e ['ability1', 'ability2', 'ability3'=\u003e'policy_module.policy'],\n    ],\n\n\n    'policies'  =\u003e [\n        /*'module' =\u003e [\n            'update'    =\u003e '\\App\\Permit\\Policies\\PostPolicy@update',\n        ],*/\n    ],\n\n\n\n    'roles' =\u003e [\n        /*'role_name' =\u003e [\n            'module.ability',\n        ],*/\n    ]\n];\n```\n\nNow run this command for migrations\n\n```shell\nphp artisan migrate\n```\n\nYou are all most done, just add this trait `Nahid\\Permit\\Users\\Permitable` in your `User` model. Example\n\n```php\nnamespace App;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Nahid\\Permit\\Users\\Permitable;\n\nclass User extends Model\n{\n    use Permitable;\n}\n```\n\nYeh, its done.\n\n## How does it work?\n\nIts a common question. But first you have to learn about our database architecture.\nWhen you run migrate command then we create a table 'permissions' with field 'role_name' and 'permission', and\nadd two column 'role' and 'permissions' in `users` table. `role` column store users role and `permissions` column store user specific controls.\nHere `role` column has a relation with `permissions.role_name` column with its controls. `permissions.permission` handle role based control.\n\nWe store permissions as JSON format with specific modules and abilities.\n\n```json\n{\n    \"user\": {\n        \"create\": true,\n        \"update\": true\n    },\n    \"post\": {\n        \"create\": false,\n        \"update\":\"\\\\App\\\\Permit\\\\Policies\\\\PostPolicy@update\",\n        \"delete\": true\n    }\n}\n```\n\nHere `user` and `post` is a service/module name and `create`, `update` and `delete` or others are abilities.\n\n### Set User Role\n\n##### Syntax\n\n`bool Permit::setUserRole(int $user_id, string $role_name)`\n\n##### Example\n\n```php\nPermit::setUserRole(1, 'admin');\n```\n\n### Set User Permission\n\n##### Syntax\n\n`bool Permit::setUserPermissions(int $user_id, string $module, array $abilities)`\n\n##### Example\n\n```php\nPermit::setUserPermissions(1, 'post', ['create'=\u003etrue, 'update'=\u003etrue]);\n```\n\n\n### Set Role Permission\n\n##### Syntax\n\n`bool Permit::setRolePermissions(string $role_name, string $module, array $abilities)`\n\n##### Example\n\n```php\nPermit::setRolePermissions('admin', 'post', ['create'=\u003etrue, 'update'=\u003etrue]);\n```\n\n\n## How to Authorize an event?\n\n### Check user ability\n\n```php\n$user = User::find(1);\n\nif (Permit::userCan($user, 'post.create')) {\n    //do something\n}\n```\nIn `post.create` is an event with module/service. Here `post` is a module and `create` is an ability.\n\nSo if the user is authorized with post create event then the user will be passed.\n\n`Permit::userCan()` method return boolean. If you want to throw Unauthorized exception you may use\n\n`Permit::userAllows()` with same parameters.\n\n### Check user role ability\n\n```php\n$user = User::find(1);\n\nif (Permit::roleCan($user, 'post.create')) {\n    //do something\n}\n```\n\nHere when given users role allowed this event then its passed. Here is a similar method for throw exception\n\n`Permit::roleAllows()`\n\n### Check Users all ability\n\nYou can check user ability from user or user role. Here we check both(user and role) permissions but if user specific permission was set then its priority will be first.\n\n```php\n$user = User::find(1);\n\nif (Permit::can($user, 'post.create')) {\n    //do something\n}\n```\n\nand here is a alternate method for throw exception\n\n`Permit::allows()`\n\n\n## Policy\n\nPolicy is a feature like laravel native authorization but its quite easy. Permit allows you to manage ACL and Authorization in a same line.\nI know your first question is where we use `Policy`?\n\nLets see an example, suppose you have a user commenting system where every user comment under a blog post and comment owner can edit and deletes their comments.\nSo you have to apply an authorization system where user can modify his/her own comment. So here we have to implement our custom policy. Take a look\n\n#### Make a policy\n\nFirst we have to create a class for policy. \n\n```php\nnamespace App\\Policies;\n\nuse App\\Comment;\nuse App\\User;\n\nclass CommentPolicy\n{\n    public function update(User $user, Comment $comment)\n    {\n        return $user-\u003eid == $comment-\u003euser_id;\n    }\n}\n```\n\nand now map this policy with our config file. Go to `config/permit.php` and update this section in `policies\n\n```php\n    ,'policies'  =\u003e [\n        'comment'  =\u003e [\n            'update'    =\u003e '\\App\\Policies\\CommentPolicy@update'\n        ]\n    ]\n```\n\nNow you have bind this policy with an ability. Suppose we have a module about comment. so this ability will look like in `config/permit.php` `abilities` section\n\n```php\n\"comment\"  =\u003e ['create', 'update'=\u003e'comment.update', 'delete'],\n```\nhere `'update'=\u003e'comment.update'` update is an ability and `comment.update` is a policy. This system are bind policy with ability.\nso now you can use this policy like a general ability.\n\nYou can predefined your all roles permissions in config file. First set your aprox abilities and then assign abilities to roles. Take a look\n\n```php\n'abilities'   =\u003e [\n        \"comment\"  =\u003e ['create', 'update'=\u003e'comment.update', 'delete'],\n        \"user\"  =\u003e ['create', 'update', 'delete'],\n    ],\n\n    'roles' =\u003e [\n        'admin' =\u003e [\n            'post.*',\n            'user.*',\n        ],\n\n        'user'    =\u003e [\n            'post.create',\n            'post.update',\n            'user.create',\n            'user.update',\n        ]\n    ],\n\n    'policies'  =\u003e [\n        'comment'  =\u003e [\n            'update'    =\u003e '\\App\\Policies\\CommentPolicy@update'\n        ]\n    ]\n```\n\nHere admin and user are role and its value is permissions or abilities. But you can't use this because its not synced with database. so run this command from your terminal\n\n```shell\nphp artisan permit:sync\n```\n\n#### How to use policy based ability\n\nIn previous section we are bind `comment.update` policy with an ability and thats are same name. Lets check currently opened comment is authorized for logged in user.\n\n```php\n$comment = Comment::find(1);\nPermit::allows(auth()-\u003euser(), 'comment.update', [$comment]);\n```\nhere first parameter is authorized user, second one is permission and third one is policy method's parameter. we are always automatically bind authenticated user as a first parameter\nand then others parameter will pass.\n\nYou can use others method like `roleCan`, 'userCan', all helper functions and blade directives as same procedure.\n\nSometimes you have to check if the given user able to perform for any ability. so we make it easy. lets see\n\n```php\nPermit::allows(auth()-\u003euser(), ['post.create', 'comment.create']);\n```\n\nBut if your ability was bind with a policy and its required paramters, then you can pass abilities with associative array.\n\n```php\n$comment = Comment::find(1);\nPermit::allows(auth()-\u003euser(), ['post.create', 'comment.update'=\u003e[$comment], 'comment.create']);\n```\n\nHere if the given user is assigned to any one abilities then its allows.\n\n### Commands\n\nWe provide several command for make user experience better\n\n### `php artisan permit:sync`\n\nSync with your composed permissions with database.\n\n### `php artisan permit:set`\n\nAdd permission to an user or role\n\n### `php artisan permit:remove`\n\nRemove permissions from an user or role\n\n### `php artisan permit:fetch`\n\nGet permissions of an user or a role\n\n### `php artisan permit:role`\n\nCreate a new role\n\n### Helper functions\n\nHere you can use helper function instead of facades.\n\n#### user_can()\n\nYou can use `user_can()` instead of `Permit::userCan()`\n\n#### user_allows()\n\nYou can use `user_allows()` instead of `Permit::userAllows()`\n\n#### role_can()\n\nYou can use `role_can()` instead of `Permit::roleCan()`\n\n#### role_allows()\n\nYou can use `role_allows()` instead of `Permit::roleAllows()`\n\n#### canDo()\n\nYou can use `canDo()` instead of `Permit::can()`\n\n#### allows()\n\nYou can use `allows()` instead of `Permit::allows()\n\n\n## Blade Directives\n\nSometimes you may want to use this functionalities in you view. Permit comes with all blade directives.\n\n\n#### Example\n\n```\n@userCan($user, 'post:create')\n    \u003ca href=\"#\"\u003eLink\u003c/a\u003e\n@endUserCan\n```\n\nYou can also use else directive\n\n```\n@userCan($user, 'post:create')\n    \u003ca href=\"#\"\u003eLink\u003c/a\u003e\n@elseDo\n    \u003ca href=\"#\"\u003eLink 2\u003c/a\u003e\n@endUserCan\n```\n\n#### List of directives\n\n- `@userCan()`\n- `@elseUserCan`\n- `@endUserCan()`\n- `@roleCan()`\n- `@elseRoleCan()`\n- `@endRoleCan()`\n- `@allows()`\n- `@endAllows()`\n- `@elseAllows()`\n\nIf you have any kind of query, please feel free to share with me\n\nThank you\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahid%2Fpermit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnahid%2Fpermit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahid%2Fpermit/lists"}