Upgrading | laravel-permission | Spatie

 SPATIE

  Laravel Permission
=====================

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-permission](https://spatie.be/docs/laravel-permission/v5)  Upgrading

 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                                                                                                                                                                                                                                    `

Upgrading
=========

###  On this page

1. [ Upgrade Essentials ](#content-upgrade-essentials)
2. [ Upgrading from v4 to v5 ](#content-upgrading-from-v4-to-v5)
3. [ Upgrading from v3 to v4 ](#content-upgrading-from-v3-to-v4)
4. [ Upgrading from v2 to v3 ](#content-upgrading-from-v2-to-v3)
5. [ Upgrading from v1 to v2 ](#content-upgrading-from-v1-to-v2)

Upgrade Essentials
--------------------------------------------------------------------------------------------------------------

ALL upgrades of this package should follow these steps:

1. Composer. Upgrading between major versions of this package always require the usual Composer steps:

    - Update your `composer.json` to specify the new major version, such as `^6.0`
    - Then run `composer update`.
2. Migrations. Compare the `migration` file stubs in the NEW version of this package against the migrations you've already run inside your app. If necessary, create a new migration (by hand) to apply any new database changes.
3. Config file. Incorporate any changes to the permission.php config file, updating your existing file. (It may be easiest to make a backup copy of your existing file, re-publish it from this package, and then re-make your customizations to it.)
4. Models. If you have made any custom Models by extending them into your own app, compare the package's old and new models and apply any relevant updates to your custom models.
5. Custom Methods/Traits. If you have overridden any methods from this package's Traits, compare the old and new traits, and apply any relevant updates to your overridden methods.
6. Contract/Interface updates. If you have implemented this package's contracts in any models, check to see if there were any changes to method signatures. Mismatches will trigger PHP errors.
7. Apply any version-specific special updates as outlined below...
8. Review the changelog, which details all the changes: [CHANGELOG](https://github.com/spatie/laravel-permission/blob/main/CHANGELOG.md)and/or consult the [Release Notes](https://github.com/spatie/laravel-permission/releases)

Upgrading from v4 to v5
-----------------------------------------------------------------------------------------------------------------------------

Follow the instructions described in "Essentials" above.

Upgrading from v3 to v4
-----------------------------------------------------------------------------------------------------------------------------

Update `composer.json` as described in "Essentials" above.

Upgrading from v2 to v3
-----------------------------------------------------------------------------------------------------------------------------

Update `composer.json` as described in "Essentials" above.

Upgrading from v1 to v2
-----------------------------------------------------------------------------------------------------------------------------

There were significant database and code changes between v1 to v2.

If you're upgrading from v1 to v2, there's no built-in automatic migration/conversion of your data to the new structure. You will need to carefully adapt your code and your data manually.

Tip: @fabricecw prepared [a gist which may make your data migration easier](https://gist.github.com/fabricecw/58ee93dd4f99e78724d8acbb851658a4).

You will also need to remove your old `laravel-permission.php` config file and publish the new one `permission.php`, and edit accordingly (setting up your custom settings again in the new file, where relevant).
