Laravel Upgrades: How to Plan and Execute an Upgrade Safely

Laravel upgrades are the process of moving an application from one Laravel version to another while validating PHP compatibility, dependencies, and tests. With each release (and Laravel sets an aggressive release pace), new enhancements are added that make it easier to build reliable and performant applications. However, falling behind on upgrades leaves applications exposed to vulnerabilities and compatibility issues that will be costly to fix later.

In this blog, I walk through why Laravel upgrades matter, outlining key considerations and possible roadblocks to consider while planning your migration or modernization project. Next, I explore a few strategies for successful upgrades and recommend resources to streamline your process.

Why Laravel Upgrades Matter

Staying current with software updates is a fundamental principle of modern PHP application development. For users of the Laravel framework, it’s crucial to keep Laravel up to date for access to the latest security functionalities and new features. After all, not only does Laravel focus on performance with each release, but it also tends to come out with great features for developers. For example, native health checks are built-in by default in Laravel 12.

Ignoring these updates can leave your application vulnerable and prevent you from leveraging tools that could significantly boost your productivity and your application's capabilities. Even more important, especially in today’s world of malicious actors using AI and other automated tools, it’s key to stay on the latest edition of Laravel to ensure your application is as secure as possible against the latest PHP vulnerabilities.

Key Considerations for Planning Laravel Upgrades

Laravel upgrades are not just a matter of running a command and hoping for the best, but a strategic process that demands careful planning. Here, I walk through three considerations for teams planning a Laravel upgrade, covering diagnosing the gap between your current and target Laravel version, evaluating Laravel PHP requirements, and accounting for PHP dependency management.

Gap Between Current and Target Laravel Versions

When planning your Laravel upgrade, one of the first things to consider is the incompatibilities your source code may have with the target version. Frameworks typically have release notes for each version, and Laravel is no exception - for example, here are the Laravel 12 release notes. This is the first place you should look for incompatibilities, because release notes always outline breaking changes.

If your target version is multiple versions away from your current version, make sure to check each version’s release notes. It’s recommended to upgrade in stages, stepping from one version to the next, checking for breaking changes and ensuring the application runs without error. This way, you’re not compounding issues while upgrading.

PHP Version Requirements

Take note that the release notes mentioned above also outline the PHP version requirements for that release. If your current version isn’t too far behind, maybe only one or two major versions behind, it’s likely that the PHP version you’re currently using is supported. 

There will be exceptions. If your PHP version is the oldest supported by your Laravel version, it’s likely to not be supported by the next version of Laravel. For example, if you’re using Laravel 10 on PHP 8.1 and want to upgrade to Laravel 11, you’ll need to upgrade PHP first, because Laravel 11 only supports PHP 8.2 through 8.4. 

This is why it’s recommended to run the latest release of PHP that your version of Laravel allows. If you’re using Laravel 10, you should do your best to run PHP 8.3. If you’re using Laravel 11, you should run PHP 8.4, and so on.

Learn More About Laravel PHP Requirements

Updating Dependencies

Updating dependencies is tricky. Some could be abandoned. Some could be lagging PHP versions, causing you to wait to upgrade your framework. Just like above, it’s good to isolate risks and upgrade dependencies one at a time separate from Laravel itself, especially if your target Laravel version requires a newer version of the dependency. 

Laravel Upgrades: Potential Roadblocks and Challenges

While some Laravel upgrades can be straightforward, most modern applications introduce custom elements that make the process more complex. From dealing with custom code that tools like Laravel Shift can’t fully automate, to managing breaking changes across versions, to navigating the pitfalls of insufficient test coverage, each step requires careful planning and execution.

Custom Code and the Limitations of Laravel Shift

Laravel Shift works great for source code that leverages Laravel. However, if your source code has a lot of complex custom code, Laravel Shift won’t catch it all, and you’ll have to manually upgrade those portions. This can extend migration timelines and eat valuable developer time, resources, and attention.

Learn More About When (and When Not) to Use Laravel Shift

Managing Breaking Changes Between Laravel Versions

As previously stated, it’s good to look at the release notes to find a brief explanation of breaking changes. Laravel takes this a step further and releases guides for upgrading versions. It’s important to note these guides are relevant for the last version of Laravel, so it’s still a good idea to go version by version for your upgrade.

Insufficient Test Coverage

If you don’t have full test coverage (or worse, none) upgrades are going to be cumbersome and tedious. You will be required to manually test all the behavior piece by piece, paying painful attention to each piece of the logic to make sure nothing is miscalculated or behaving improperly. 

In fact, it’s recommended to go ahead and take the time to build out an automated testing suite. Even if it’s not full coverage, if it covers all the crucial features of your application, future you will be thankful. Since you’re going to need to take the time to test thoroughly anyway, why not automate it while you’re at it?

Learn More About PHP Testing

Successful Laravel Upgrades Checklist

Now that we've covered considerations for evaluating your specific Laravel upgrade and explored potential challenges to watch for, let's move on to best practices for successful Laravel upgrades. These include implementing incremental updates, using comprehensive testing throughout your project, and upgrading dependencies alongside Laravel versions.

Implement Incremental Updates

It is highly recommended to upgrade incrementally. Laravel versions typically overlap PHP versions to allow for this. Let’s use Laravel 10 on PHP 8.1 with a target upgrade to Laravel 13 as an example. Ideally your upgrade path would look something like:

1. Upgrade PHP from PHP 8.1 to 8.2 (minimum version supported by Laravel 11)
   1. Or go straight to 8.3 then 8.4 if you’re comfortable and it makes sense to
2. Upgrade Laravel from 10 to 11
3. Upgrade Laravel from 11 to 12
4. Upgrade PHP from 8.2 to 8.3 (minimum version supported by Laravel 13)
5. Upgrade Laravel from 12 to 13

Use Comprehensive Testing Strategies

At the very least, it's good to use unit tests to have confidence that all classes, class methods, and functions are behaving properly and providing proper output. It’s even better to implement automated end-to-end tests, UI tests, and performance/load tests. 

Otherwise, you’re stuck doing it all manually. Not only can this become a massive time sink, but it can also be extremely stressful and keep you up at night wondering, will that production push crash on Monday and leave a lot of users with bugs, costing us precious revenue and user sentiment?

Upgrade Application Dependencies Alongside Laravel Versions

We briefly covered upgrading and PHP dependency management, and the importance of isolating them and performing their update separately from the Laravel upgrade. However, this isn’t always possible. Sometimes dependency versions don’t overlap with the framework versions and vice versa. For example, Laravel 11 might depend on Dependency v3 and Laravel 12 might depend on Dependency v4, or Dependency v3 depends on Laravel 11 and Dependency v4 depends on Laravel 12. In this very rare case, you’re stuck updating your dependency alongside the Laravel upgrade.

If this is the case, I’d still recommend isolating application behavior related to the dependency and testing it thoroughly before moving on to the rest of the framework upgrade.

Final Thoughts

Laravel upgrades are essential for maintaining secure and functional applications, but the process requires considerable expertise, time, and developer resources. From managing breaking changes to ensuring compatibility with PHP versions and dependencies, each step requires careful planning, execution, and testing. Your best option may be to outsource your Laravel upgrade or migration to a trusted third party, like Zend.

Zend provides hands-on Laravel Migration Support, helping you anticipate potential roadblocks, minimize downtime, and ensure your Laravel applications are optimized for success. Get full Laravel upgrade coverage, extend the lifespan of EOL PHP versions by at least two years, and improve your stack.

Additional Resources

• Case Study - How Zend Saved Bark.com 20+ Weeks of Engineering Work via Modernization Services
• White Paper - The Hidden Costs of PHP Upgrades
• White Paper - Planning Your Next PHP Migration
• Blog - What's the Best PHP Framework for Web Development?
• Blog - PHP Migration and Version Adoption Trends
• Blog - Laravel vs. Symfony: Which Is Right for Your Web App?