Upgrading with Laravel Shift - Full process with useful troubleshooting tips

Laravel applications can be manually upgraded by following the upgrade guide provided in the Laravel documentation.

Alternatively, you can use a service like Laravel Shift which will automate a lot of the upgrade process. If you’re making a single version jump (e.g. v8 → v9) the Shift service costs ~$20 and the time it saves can definitely be worth the cost.

That being said, it’s important to understand that while Shift will automate a lot of the upgrade process, there’s still manual work that needs to happen to make sure your application is working smoothly once the upgrade is complete.

In the video, I show the upgrade process from start to finish and cover a lot of the common things you’ll need to address after doing an upgrade with Shift. Below is a summary of some of the key points hit in the video.

Testing

If you have a testing set up in place, the first step to any upgrade process is to run your tests and make sure they’re running 100% before upgrading. That way - post-upgrade - you can run your tests again and feel confident you didn’t break anything during the upgrade process.

Laravel Shift in a nutshell

To upgrade an application with Laravel Shift, you will follow these steps:

Choose and purchase an upgrade plan at LaravelShift.com.
Grant Shift access to the repository of the application you are upgrading - Shift will create a branch on your repository with a series of commits and comments with all the upgrade changes.

In your development environment, you will pull down the branch Shift created to review the changes and confirm everything is working.
- After pulling down and switching to the Laravel Shift branch, you should run composer update to grab the latest dependencies and php artisan cache:clear to flush your application cache.
- Additionally, you should review each comment left by the Shift pull request to address any changes/updates that Shift was not able to automate (notes on this below).
- After completing the above steps you will want to ensure your application is functioning as expected both via automated tests (if available) and manual testing.
Once everything is working as expected, you can commit any changes you made and merge the Shift branch into your main branch then deploy your changes to production. Don't forget to update your dependencies (composer install --no-dev) and clear your cache (php artisan cache:clear) on production, just as you did in development.

Laravel Shift comments

As part of the pull request Laravel Shift will initiate against your repository (examples screenshot above), you will see a series of comments left by Shift that you will need to review. These comments address aspects of the upgrade that Shift was not able to automate, or just general things you should be aware of.

For example, you will typically see a comment about environment variables in your .env file. Because this file can contain sensitive credentials it is conventionally excluded from version control, and thus Shift will not be able to access/upgrade it. As a result, you may need to make manual changes to this file following the instructions Shift provides in the comments.

Read each comment carefully and decide whether you need to take any additional further action.

Dependency incompatibilities

After upgrading, you might find that some of the dependencies you’re using are not compatible with the version of Laravel you are upgrading to.

When this happens, you will need to check and see if those dependencies themselves have an update. In the video, we see this happen with the the Laravel-Markdown dependency I was using.

Because of this potential for incompatibilities, I typically wait a month or so for a new Laravel release to be out before doing upgrades. This gives the developers of the dependencies I use the opportunity to update their software.

If the dependencies you’re using does not have updates you need to either a) find a different dependency or b) fork the dependency and do your own upgrade. Doing the upgrade can be as simple as just bumping up the minimum Laravel version requirement of the package, or as complex as reworking the dependency if parts of its code is not compatible with the changes introduced by Laravel.

Concluding notes