Prerequisites | laravel-permission | Spatie SPATIE Laravel Permission ===================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-permission](https://spatie.be/docs/laravel-permission/v5) Prerequisites 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/v5/introduction) - [ Support us ](https://spatie.be/docs/laravel-permission/v5/support-us) - [ Prerequisites ](https://spatie.be/docs/laravel-permission/v5/prerequisites) - [ Installation in Laravel ](https://spatie.be/docs/laravel-permission/v5/installation-laravel) - [ Installation in Lumen ](https://spatie.be/docs/laravel-permission/v5/installation-lumen) - [ Upgrading ](https://spatie.be/docs/laravel-permission/v5/upgrading) - [ Questions and issues ](https://spatie.be/docs/laravel-permission/v5/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-permission/v5/changelog) - [ About us ](https://spatie.be/docs/laravel-permission/v5/about-us) Basic Usage ----------- - [ Basic Usage ](https://spatie.be/docs/laravel-permission/v5/basic-usage/basic-usage) - [ Direct Permissions ](https://spatie.be/docs/laravel-permission/v5/basic-usage/direct-permissions) - [ Using Permissions via Roles ](https://spatie.be/docs/laravel-permission/v5/basic-usage/role-permissions) - [ Enums ](https://spatie.be/docs/laravel-permission/v5/basic-usage/enums) - [ Teams permissions ](https://spatie.be/docs/laravel-permission/v5/basic-usage/teams-permissions) - [ Wildcard permissions ](https://spatie.be/docs/laravel-permission/v5/basic-usage/wildcard-permissions) - [ Blade directives ](https://spatie.be/docs/laravel-permission/v5/basic-usage/blade-directives) - [ Using a middleware ](https://spatie.be/docs/laravel-permission/v5/basic-usage/middleware) - [ Defining a Super-Admin ](https://spatie.be/docs/laravel-permission/v5/basic-usage/super-admin) - [ Using multiple guards ](https://spatie.be/docs/laravel-permission/v5/basic-usage/multiple-guards) - [ Using artisan commands ](https://spatie.be/docs/laravel-permission/v5/basic-usage/artisan) - [ Example App ](https://spatie.be/docs/laravel-permission/v5/basic-usage/new-app) Best Practices -------------- - [ Roles vs Permissions ](https://spatie.be/docs/laravel-permission/v5/best-practices/roles-vs-permissions) - [ Model Policies ](https://spatie.be/docs/laravel-permission/v5/best-practices/using-policies) - [ Performance Tips ](https://spatie.be/docs/laravel-permission/v5/best-practices/performance) Advanced usage -------------- - [ Testing ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/testing) - [ Database Seeding ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/seeding) - [ Exceptions ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/exceptions) - [ Extending ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/extending) - [ Cache ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/cache) - [ Custom Permission Check ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/custom-permission-check) - [ UUID ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/uuid) - [ PhpStorm Interaction ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/phpstorm) - [ Other ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/other) - [ Timestamps ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/timestamps) - [ UI Options ](https://spatie.be/docs/laravel-permission/v5/advanced-usage/ui-options) You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command: ` composer show spatie/laravel-permission ` Prerequisites ============= ### On this page 1. [ Laravel Version ](#content-laravel-version) 2. [ User Model / Contract/Interface ](#content-user-model--contractinterface) 3. [ Must not have a \[role\] or \[roles\] property, nor a \[roles()\] method ](#content-must-not-have-a-role-or-roles-property-nor-a-roles-method) 4. [ Must not have a \[permission\] or \[permissions\] property, nor a \[permissions()\] method ](#content-must-not-have-a-permission-or-permissions-property-nor-a-permissions-method) 5. [ Config file ](#content-config-file) 6. [ Schema Limitation in MySQL ](#content-schema-limitation-in-mysql) 7. [ Note for apps using UUIDs/ULIDs/GUIDs ](#content-note-for-apps-using-uuidsulidsguids) 8. [ Database foreign-key relationship support ](#content-database-foreign-key-relationship-support) Laravel Version ----------------------------------------------------------------------------------------------------- This package can be used in Laravel 6 or higher. Check the "Installing on Laravel" page for package versions compatible with various Laravel versions. User Model / Contract/Interface ------------------------------------------------------------------------------------------------------------------------------------------------- This package uses Laravel's Gate layer to provide Authorization capabilities. The Gate/authorization layer requires that your `User` model implement the `Illuminate\Contracts\Auth\Access\Authorizable` contract. Otherwise the `can()` and `authorize()` methods will not work in your controllers, policies, templates, etc. In the `Installation` instructions you'll see that the `HasRoles` trait must be added to the User model to enable this package's features. Thus, a typical basic User model would have these basic minimum requirements: ``` use Illuminate\Foundation\Auth\User as Authenticatable; use Spatie\Permission\Traits\HasRoles; class User extends Authenticatable { use HasRoles; // ... } ``` Must not have a \[role\] or \[roles\] property, nor a \[roles()\] method -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Your `User` model/object MUST NOT have a `role` or `roles` property (or field in the database by that name), nor a `roles()` method on it. Those will interfere with the properties and methods added by the `HasRoles` trait provided by this package, thus causing unexpected outcomes when this package's methods are used to inspect roles and permissions. Must not have a \[permission\] or \[permissions\] property, nor a \[permissions()\] method -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Your `User` model/object MUST NOT have a `permission` or `permissions` property (or field in the database by that name), nor a `permissions()` method on it. Those will interfere with the properties and methods added by the `HasPermissions` trait provided by this package (which is invoked via the `HasRoles` trait). Config file ----------------------------------------------------------------------------------------- This package publishes a `config/permission.php` file. If you already have a file by that name, you must rename or remove it, as it will conflict with this package. You could optionally merge your own values with those required by this package, as long as the keys that this package expects are present. See the source file for more details. Schema Limitation in MySQL -------------------------------------------------------------------------------------------------------------------------------------- MySQL 8.0 limits index keys to 1000 characters. This package publishes a migration which combines multiple columns in single index. With `utf8mb4` the 4-bytes-per-character requirement of `mb4` means the max length of the columns in the hybrid index can only be `125` characters. Thus in your AppServiceProvider you will need to set `Schema::defaultStringLength(125)`. [See the Laravel Docs for instructions](https://laravel.com/docs/migrations#index-lengths-mysql-mariadb). Note for apps using UUIDs/ULIDs/GUIDs ------------------------------------------------------------------------------------------------------------------------------------------------------------------- This package expects the primary key of your `User` model to be an auto-incrementing `int`. If it is not, you may need to modify the `create_permission_tables` migration and/or modify the default configuration. See for more information. Database foreign-key relationship support ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To enforce database integrity, this package uses foreign-key relationships with cascading deletes. This prevents data mismatch situations if database records are manipulated outside of this package. If your database engine does not support foreign-key relationships, then you will have to alter the migration files accordingly. IMPROVEMENTS TO FOREIGN KEY HANDLING WERE ADDED IN v6, SO UPGRADING IS RECOMMENDED.