{"id":24962391,"url":"https://github.com/directorytree/authorization","last_synced_at":"2025-05-16T02:09:23.690Z","repository":{"id":43751758,"uuid":"401547596","full_name":"DirectoryTree/Authorization","owner":"DirectoryTree","description":"Easy, native Laravel user authorization.","archived":false,"fork":false,"pushed_at":"2025-03-10T14:29:07.000Z","size":215,"stargazers_count":176,"open_issues_count":3,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-12T20:17:18.219Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DirectoryTree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","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,"zenodo":null}},"created_at":"2021-08-31T02:25:27.000Z","updated_at":"2025-04-10T04:55:07.000Z","dependencies_parsed_at":"2024-01-29T18:04:02.109Z","dependency_job_id":"332b288d-9ed8-4214-a769-06cd477fe78b","html_url":"https://github.com/DirectoryTree/Authorization","commit_stats":{"total_commits":178,"total_committers":6,"mean_commits":"29.666666666666668","dds":0.1235955056179775,"last_synced_commit":"18faee96ac9a57e72dd2826b6f0d0b2b5d122309"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirectoryTree%2FAuthorization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirectoryTree%2FAuthorization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirectoryTree%2FAuthorization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirectoryTree%2FAuthorization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DirectoryTree","download_url":"https://codeload.github.com/DirectoryTree/Authorization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254453667,"owners_count":22073618,"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":[],"created_at":"2025-02-03T09:00:03.063Z","updated_at":"2025-05-16T02:09:23.671Z","avatar_url":"https://github.com/DirectoryTree.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- readme.md --\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/DirectoryTree/Authorization/blob/master/art/logo.svg\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/DirectoryTree/Authorization/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/directorytree/authorization/run-tests.yml?branch=master\u0026style=flat-square\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/DirectoryTree/Authorization\"\u003e\u003cimg src=\"https://img.shields.io/packagist/dt/DirectoryTree/Authorization.svg?style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/DirectoryTree/Authorization\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/DirectoryTree/Authorization.svg?style=flat-square\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/DirectoryTree/Authorization\"\u003e\u003cimg src=\"https://img.shields.io/github/license/DirectoryTree/Authorization.svg?style=flat-square\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nAn easy, native role / permission management system for Laravel.\n\u003c/p\u003e\n\n## Index\n\n-   [Installation](#installation)\n    -   [Migration Customization](#migration-customization)\n    -   [Model Customization](#model-customization)\n-   [Usage](#usage)\n-   [Checking Permissions \u0026 Roles](#checking-permissions--roles)\n-   [Caching](#caching)\n-   [Gate Registration](#gate-registration)\n-   [Middleware](#middleware)\n-   [Testing](#running-tests)\n\n## Installation\n\nTo get started, install Authorization via the Composer package manager:\n\n    composer require directorytree/authorization\n\nThe Authorization service provider registers its own database migration directory\nwith the framework, so you should migrate your database after installing the\npackage. The Authorization migrations will create the tables your\napplication needs to store roles and permissions:\n\n    php artisan migrate\n\nNow insert the `DirectoryTree\\Authorization\\Traits\\Authorizable` onto your `App\\Models\\User` model:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse DirectoryTree\\Authorization\\Traits\\Authorizable;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable\n{\n    use Authorizable;\n\n    // ...\n}\n```\n\nYou can now perform user authorization.\n\n### Migration Customization\n\nIf you would not like to use Authorization's default migrations, you should call the\n`Authorization::ignoreMigrations` method in the `register` method of your\n`AppServiceProvider`. You may export the default migrations using\n`php artisan vendor:publish --tag=authorization-migrations`.\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any application services.\n *\n * @return void\n */\npublic function register()\n{\n    Authorization::ignoreMigrations();\n}\n```\n\n### Model Customization\n\nBy default, the `App\\Models\\User` class is registered as the authorizable user model.\n\nYou're free to extend the models used internally by Authorization, or create your own.\n\nInstruct Authorization to use your own models via the `Authorization` class in your `AuthServiceProvider`:\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any authentication / authorization services.\n *\n * @return void\n */\npublic function boot()\n{\n    $this-\u003eregisterPolicies();\n\n    Authorization::useUserModel(\\App\\Models\\User::class);\n    Authorization::useRoleModel(\\App\\Models\\Role::class);\n    Authorization::usePermissionModel(\\App\\Models\\Permission::class);\n}\n```\n\nBe sure to add the relevant traits for each of your custom models:\n\n**Role Model**:\n\n```php\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse DirectoryTree\\Authorization\\Traits\\ManagesPermissions;\n\nclass Role extends Model\n{\n    use ManagesPermissions;\n}\n```\n\n**Permission Model**:\n\n```php\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse DirectoryTree\\Authorization\\Traits\\HasUsers;\nuse DirectoryTree\\Authorization\\Traits\\HasRoles;\nuse DirectoryTree\\Authorization\\Traits\\ClearsCachedPermissions;\n\nclass Permission extends Model\n{\n    use HasUsers, HasRoles, ClearsCachedPermissions;\n}\n```\n\n## Usage\n\nAuthorization uses native Laravel relationships, so there's no need to learn a new API if you don't want to.\n\n\u003e Due to Authorization's trait based implementation, all of Authorization's functionality can be overridden or extended with you own implementation.\n\n### Managing Roles \u0026 Permissions\n\nCreate a permission:\n\n```php\nuse DirectoryTree\\Authorization\\Permission;\n\n$createUsers = Permission::create([\n    'name' =\u003e 'users.create',\n    'label' =\u003e 'Create Users',\n]);\n```\n\nCreate a role:\n\n```php\nuse DirectoryTree\\Authorization\\Role;\n\n$admin = Role::create([\n    'name' =\u003e 'administrator',\n    'label' =\u003e 'Admin',\n]);\n```\n\nGrant the permission to a role:\n\n```php\n$admin-\u003epermissions()-\u003esave($createUsers);\n```\n\nNow assign the role to the user:\n\n```php\n$user-\u003eroles()-\u003esave($admin);\n```\n\nYou may also use the `grant()` or `revoke()` method on a `Role` model:\n\n```php\n// Using the permission's name:\n$admin-\u003egrant('users.create');\n\n// Using a permission model:\n$admin-\u003egrant($permission);\n\n// Granting multiple permissions:\n$admin-\u003egrant(['users.create', 'users.edit']);\n\n// Granting a collection of models:\n$admin-\u003egrant(Permission::all());\n\n// Using a mix of models and permission name:\n$admin-\u003egrant([$createUsers, 'users.edit']);\n```\n\nYou may also sync a role's permissions using the `grantOnly()` method:\n\n```php\n// All permissions will be removed except, except for the given:\n$admin-\u003egrantOnly('users.create');\n```\n\n```php\n// Using the permission's name:\n$admin-\u003erevoke('users.create');\n\n// Using a permission model:\n$admin-\u003erevoke($permission);\n\n// Revoking multiple permissions:\n$admin-\u003erevoke(['users.create', 'users.edit']);\n\n// Revoking a collection of models:\n$admin-\u003erevoke(Permission::all());\n\n// Using a mix of models and permission name:\n$admin-\u003erevoke([$createUsers, 'users.edit']);\n```\n\nYou may also detach all permissions from a role using `revokeAll()`:\n\n```php\n$admin-\u003erevokeAll();\n```\n\n### Managing Users \u0026 Permissions\n\nYou can also create user specific permissions:\n\n```php\n$createUsers = Permission::create([\n    'name' =\u003e 'users.create',\n    'label' =\u003e 'Create Users',\n]);\n\n$user-\u003epermissions()-\u003esave($createUsers);\n```\n\nAs with roles, may also use the `grant()` or `revoke()` method on an authorizable `User` model:\n\n```php\n// Using the permission's name:\n$user-\u003egrant('users.create');\n\n// Using a permission model:\n$user-\u003egrant($permission);\n\n// Granting multiple permissions:\n$user-\u003egrant(['users.create', 'users.edit']);\n\n// Granting a collection of models:\n$user-\u003egrant(Permission::all());\n\n// Using a mix of models and permission name:\n$user-\u003egrant([$createUsers, 'users.edit']);\n```\n\nYou may also sync a users' permissions using the `grantOnly()` method:\n\n```php\n// All permissions will be removed except, except for the given:\n$user-\u003egrantOnly('users.create');\n```\n\n```php\n// Using the permission's name:\n$user-\u003erevoke('users.create');\n\n// Using a permission model:\n$user-\u003erevoke($permission);\n\n// Granting multiple permissions:\n$user-\u003erevoke(['users.create', 'users.edit']);\n\n// Granting a collection of models:\n$user-\u003erevoke(Permission::all());\n\n// Using a mix of models and permission name:\n$user-\u003erevoke([$createUsers, 'users.edit']);\n```\n\n### Checking Permissions \u0026 Roles\n\nUsing Laravel's native `can()` method:\n\n```php\nif (Auth::user()-\u003ecan('users.create')) {\n    // This user can create other users.\n}\n```\n\nUsing Laravel's native `authorize()` method in your controllers:\n\n```php\npublic function create()\n{\n    $this-\u003eauthorize('users.create');\n\n    User::create(['...']);\n}\n```\n\nUsing Laravel's native `Gate` facade:\n\n```php\nif (Gate::allows('users.create')) {\n    //\n}\n```\n\nUsing Laravel's native `@can` directive in your views:\n\n```blade\n@can('users.create')\n    \u003c!-- This user can create other users. --\u003e\n@endcan\n```\n\n### Checking Permissions \u0026 Roles (Using Authorization Package Methods)\n\nChecking for permission:\n\n```php\n// Using the permissions name.\nif ($user-\u003ehasPermission('users.create')) {\n    //\n}\n\n// Using the permissions model.\nif ($user-\u003ehasPermission($createUsers)) {\n    //\n}\n```\n\nChecking for multiple permissions:\n\n```php\nif ($user-\u003ehasPermissions(['users.create', 'users.edit'])) {\n    // This user has both creation and edit rights.\n} else {\n    // The user doesn't have one of the specified permissions.\n}\n```\n\nChecking if the user has any permissions:\n\n```php\nif ($user-\u003ehasAnyPermissions(['users.create', 'users.edit', 'users.destroy'])) {\n    // This user either has create, edit or destroy permissions.\n} else {\n    // The user doesn't have any of the specified permissions.\n}\n```\n\nChecking if the user has a role:\n\n```php\nif ($user-\u003ehasRole('administrator')) {\n    // This user is an administrator.\n} else {\n    // The user isn't an administrator.\n}\n```\n\nChecking if the user has specified roles:\n\n```php\nif ($user-\u003ehasRoles(['administrator', 'member'])) {\n    // This user is an administrator and a member.\n} else {\n    // The user isn't an administrator or member.\n}\n```\n\nChecking if the user has any specified roles:\n\n```php\nif ($user-\u003ehasAnyRoles(['administrator', 'member', 'guest'])) {\n    // This user is either an administrator, member or guest.\n} else {\n    // The user doesn't have any of these roles.\n}\n```\n\n### Caching\n\nBy default all permissions are cached to prevent them from being retrieved on every request.\n\nThis cache is automatically flushed when permissions are created, updated, or deleted.\n\nIf you would like to disable the cache, call `Authorization::disablePermissionCache` in your `AuthServiceProvider`:\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any authentication / authorization services.\n *\n * @return void\n */\npublic function boot()\n{\n    $this-\u003eregisterPolicies();\n\n    Authorization::disablePermissionCache();\n}\n```\n\n#### Cache Key\n\nBy default, the permission cache key is `authorization.permissions`.\n\nTo alter the cache key, call `Authorization::cacheKey` in your `AuthServiceProvider`:\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any authentication / authorization services.\n *\n * @return void\n */\npublic function boot()\n{\n    $this-\u003eregisterPolicies();\n\n    Authorization::cacheKey('my-key');\n}\n```\n\n#### Cache Expiry\n\nBy default, the permission cache will expire daily.\n\nTo alter this expiry date, call `Authorization::cacheExpiresIn` in your `AuthServiceProvider`:\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any authentication / authorization services.\n *\n * @return void\n */\npublic function boot()\n{\n    $this-\u003eregisterPolicies();\n\n    Authorization::cacheExpiresIn(now()-\u003eaddWeek());\n}\n```\n\n### Gate Registration\n\nBy default all permissions you create are registered in Laravel's Gate.\n\nIf you would like to disable this, call `Authorization::disableGateRegistration` in your `AuthServiceProvider`:\n\n```php\nuse DirectoryTree\\Authorization\\Authorization;\n\n/**\n * Register any authentication / authorization services.\n *\n * @return void\n */\npublic function boot()\n{\n    $this-\u003eregisterPolicies();\n\n    Authorization::disableGateRegistration();\n}\n```\n\n### Middleware\n\nAuthorization includes two useful middleware classes you can utilize for your routes.\n\nInsert them into your `app/Http/Kernel.php`:\n\n```php\n/**\n * The application's route middleware.\n *\n * These middleware may be assigned to groups or used individually.\n *\n * @var array\n */\nprotected $routeMiddleware = [\n    'auth' =\u003e \\App\\Http\\Middleware\\Authenticate::class,\n    'auth.basic' =\u003e \\Illuminate\\Auth\\Middleware\\AuthenticateWithBasicAuth::class,\n    'guest' =\u003e \\App\\Http\\Middleware\\RedirectIfAuthenticated::class,\n    'throttle' =\u003e \\Illuminate\\Routing\\Middleware\\ThrottleRequests::class,\n\n    // The role middleware:\n    'role' =\u003e \\DirectoryTree\\Authorization\\Middleware\\RoleMiddleware::class,\n\n    // The permission middleware:\n    'permission' =\u003e \\DirectoryTree\\Authorization\\Middleware\\PermissionMiddleware::class,\n];\n```\n\nOnce you've added them, you can start using them.\n\n\u003e **Note**: When a user does not meet the requirements using the middleware, a 403 HTTP exception is thrown.\n\nTo guard a route to only allow specific permissions:\n\n```php\nRoute::get('users', [\n    'uses' =\u003e 'UsersController@index',\n    'middleware' =\u003e 'permission:users.index',\n]);\n\n// Multiple permissions:\nRoute::get('users', [\n    'uses' =\u003e 'UsersController@index',\n    // Users must have index **and** create rights to access this route.\n    'middleware' =\u003e 'permission:users.index,users.create',\n]);\n```\n\nTo guard a route to allow a specific role:\n\n```php\nRoute::get('users', [\n    'uses' =\u003e 'UsersController@index',\n    'middleware' =\u003e 'role:administrator',\n]);\n\n// Multiple roles:\nRoute::get('users', [\n    'uses' =\u003e 'UsersController@index',\n    // Users must be an administrator **and** a member to access this route.\n    'middleware' =\u003e 'role:administrator,member',\n]);\n```\n\n### Running Tests\n\nTo run your applications tests, **you must** instantiate the `PermissionRegistrar`\ninside your `TestCase::setUp()` method **before** running your\ntests for permissions to register properly:\n\n```php\nuse DirectoryTree\\Authorization\\PermissionRegistrar;\n```\n\n```php\nprotected function setUp() : void\n{\n    parent::setUp();\n\n    app(PermissionRegistrar::class)-\u003eregister();\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirectorytree%2Fauthorization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirectorytree%2Fauthorization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirectorytree%2Fauthorization/lists"}