Installation in Laravel | laravel-permission | Spatie SPATIE Laravel Permission ===================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-permission](https://spatie.be/docs/laravel-permission/v7) Installation in Laravel Version v7 v6 v5 v4 v3 Other versions for crawler [v7](https://spatie.be/docs/laravel-permission/v7) [v6](https://spatie.be/docs/laravel-permission/v6) [v5](https://spatie.be/docs/laravel-permission/v5) [v4](https://spatie.be/docs/laravel-permission/v4) [v3](https://spatie.be/docs/laravel-permission/v3) - [ Introduction ](https://spatie.be/docs/laravel-permission/v7/introduction) - [ Support us ](https://spatie.be/docs/laravel-permission/v7/support-us) - [ Prerequisites ](https://spatie.be/docs/laravel-permission/v7/prerequisites) - [ Installation in Laravel ](https://spatie.be/docs/laravel-permission/v7/installation-laravel) - [ Upgrading ](https://spatie.be/docs/laravel-permission/v7/upgrading) - [ Questions and issues ](https://spatie.be/docs/laravel-permission/v7/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-permission/v7/changelog) - [ About us ](https://spatie.be/docs/laravel-permission/v7/about-us) Basic Usage ----------- - [ Basic Usage ](https://spatie.be/docs/laravel-permission/v7/basic-usage/basic-usage) - [ Direct Permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/direct-permissions) - [ Using Permissions via Roles ](https://spatie.be/docs/laravel-permission/v7/basic-usage/role-permissions) - [ Enums ](https://spatie.be/docs/laravel-permission/v7/basic-usage/enums) - [ Teams permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/teams-permissions) - [ Wildcard permissions ](https://spatie.be/docs/laravel-permission/v7/basic-usage/wildcard-permissions) - [ Blade directives ](https://spatie.be/docs/laravel-permission/v7/basic-usage/blade-directives) - [ Defining a Super-Admin ](https://spatie.be/docs/laravel-permission/v7/basic-usage/super-admin) - [ Using multiple guards ](https://spatie.be/docs/laravel-permission/v7/basic-usage/multiple-guards) - [ Artisan Commands ](https://spatie.be/docs/laravel-permission/v7/basic-usage/artisan) - [ Middleware ](https://spatie.be/docs/laravel-permission/v7/basic-usage/middleware) - [ Passport Client Credentials Grant usage ](https://spatie.be/docs/laravel-permission/v7/basic-usage/passport) - [ Example App ](https://spatie.be/docs/laravel-permission/v7/basic-usage/new-app) Best Practices -------------- - [ Roles vs Permissions ](https://spatie.be/docs/laravel-permission/v7/best-practices/roles-vs-permissions) - [ Model Policies ](https://spatie.be/docs/laravel-permission/v7/best-practices/using-policies) - [ Performance Tips ](https://spatie.be/docs/laravel-permission/v7/best-practices/performance) Advanced usage -------------- - [ Testing ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/testing) - [ Database Seeding ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/seeding) - [ Exceptions ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/exceptions) - [ Extending ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/extending) - [ Cache ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/cache) - [ Events ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/events) - [ Custom Permission Check ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/custom-permission-check) - [ UUID/ULID ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/uuid) - [ PhpStorm Interaction ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/phpstorm) - [ Other ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/other) - [ Timestamps ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/timestamps) - [ UI Options ](https://spatie.be/docs/laravel-permission/v7/advanced-usage/ui-options) Installation in Laravel ======================= ### On this page 1. [ Laravel Version Compatibility ](#content-laravel-version-compatibility) 2. [ Installing ](#content-installing) 3. [ Default config file contents ](#content-default-config-file-contents) Laravel Version Compatibility ----------------------------------------------------------------------------------------------------------------------------------------------- See the "Prerequisites" documentation page for compatibility details. Installing -------------------------------------------------------------------------------------- 1. Consult the **Prerequisites** page for important considerations regarding your **User** models! 2. This package **publishes a `config/permission.php` file**. If you already have a file by that name, you must rename or remove it. 3. You can **install the package via composer**: ``` composer require spatie/laravel-permission ``` 4. The Service Provider will automatically be registered; however, if you wish to manually register it, you can manually add the `Spatie\Permission\PermissionServiceProvider::class` service provider to the array in `bootstrap/providers.php`. 5. **You should publish** [the migration](https://github.com/spatie/laravel-permission/blob/main/database/migrations/create_permission_tables.php.stub) and the [`config/permission.php` config file](https://github.com/spatie/laravel-permission/blob/main/config/permission.php) with: ``` php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" ``` 6. BEFORE RUNNING MIGRATIONS - **If you are using UUIDs**, see the Advanced section of the docs on UUID steps, before you continue. It explains some changes you may want to make to the migrations and config file before continuing. It also mentions important considerations after extending this package's models for UUID capability. - **If you are going to use the TEAMS features** you must update your [`config/permission.php` config file](https://github.com/spatie/laravel-permission/blob/main/config/permission.php): - must set `'teams' => true,` - and (optional) you may set `team_foreign_key` name in the config file if you want to use a custom foreign key in your database for teams - **If you are using MySQL 8+**, look at the **Prerequisites** docs page for notes about MySQL 8+ to set/limit the index key length, and edit accordingly. If you get `ERROR: 1071 Specified key was too long` then you need to do this. - **If you are using CACHE\_STORE=database**, be sure to [install Laravel's cache migration](https://laravel.com/docs/cache#prerequisites-database), else you will encounter cache errors. 7. **Clear your config cache**. This package requires access to the `permission` config settings in order to run migrations. If you've been caching configurations locally, clear your config cache with either of these commands: ``` php artisan optimize:clear # or php artisan config:clear ``` 8. **Run the migrations**: After the config and migration have been published and configured, you can create the tables for this package by running: ``` php artisan migrate ``` 9. **Add the necessary trait to your User model**: ``` // The User model requires this trait use HasRoles; ``` 10. Consult the **Basic Usage** section of the docs to get started using the features of this package. . Default config file contents -------------------------------------------------------------------------------------------------------------------------------------------- You can view the default config file contents at: