As a developer, you will likely have found yourself facing the challenge of bringing outdated software up to date. You know you’re missing out on the latest features and improvements, but maybe the demands of work and project delivery tend to take precedence over the underlying task of upgrading? Before you know it, you’re several versions behind, out of support, and the gap to catch up keeps growing.
We’ve helped many of our clients with upgrade projects in the past, so we wanted to share our approach to upgrading larger legacy Laravel systems, offering guidance and support for those facing similar challenges.
Take Stock of the Technical Problem
Upgrading legacy applications can be an arduous task, often difficult to estimate accurately. Carrying out a short discovery process in advance can help gauge the scale of the upgrade and help you formulate an effective plan of action. Ideally, your application should always be on a currently supported version of Laravel to receive bug fixes and security patches. The further behind you are, the more challenging the upgrade process becomes. Ideally upgrading your application should be regularly scheduled like a car MOT rather than leaving it until the wheels and doors are falling off!
We have found that upgrading is generally easier with the later versions of Laravel, with applications having to upgrade through versions 5 and 6 requiring more higher effort. While more recent versions have improved upgrade processes, keep in mind the overall age of your application and that older dependencies may not be fully supported in newer Laravel versions. Utilising tools such as Laravel Shift’s – ‘Can I upgrade Laravel yet?’ to check dependency compatibility in advance can help identify potential challenges and facilitate smoother upgrades.
Document Findings and Consider Other Software Dependencies
Throughout the discovery process, we always document our findings in detail. This ensures that future iterations of the upgrade process benefit from the time invested up front. Additionally, you must consider the impact of upgrades on other software components, such as PHP versions and front-end technologies. Compile a list of these dependencies so you can determine whether they need to be included with the current iteration or can be scheduled for future upgrade work. Note that as significant versions of PHP and Laravel are released annually you may find both need to be upgraded at the same time.
Any application of significant complexity will depend on packages and libraries that may become unsupported and defunct over time. When we come across a dependency that is unsupported the first thing we check is whether or not that functionality is actually still required by end users, we’ve been able to save a lot of time in the past simply removing code that is no longer required. If the functionality is still required you will need to investigate whether a viable alternative is provided by another supported package or you may find the feature is now supported natively by a newer version of Laravel. Either way, you will need to consider the time and risks of reworking the code here.
Understand the Business Impact
If you are managing a business critical application, especially one that is large, complex, or running on an outdated Laravel version, you’ll need to give consideration to the wider business impact of carrying out the upgrade. Securing backing from key decision makers may prove challenging but showing your understanding of the business impacts your upgrade plan may have will increase stakeholder buy-in. Consider potential development freezes during the upgrade process and evaluate how long they can realistically be sustained. Ensure that ongoing projects and branches are merged in advance to avoid complications and any loss of work. Be transparent and realistic about any downtime required for transitioning to the upgraded application. If we’re upgrading an application that is used by internal business users only, we often run old and new systems concurrently for a short period as a safety measure.
Set Realistic Expectations and Highlight Costs
Be prepared to answer the inevitable question: How long will it take? For smaller systems or a few version upgrades, estimation may be feasible, but for larger systems, it is advisable to set a fixed timeline and focus on making progress within that window. Emphasise the objective of shipping a working and stable version as a step forward, rather than promising a fully updated application by a specific date. Recognise the costs associated with the upgrade, whether it involves conducting the work internally or outsourcing it to a Laravel Partner such as ourselves. Account for development time, testing by internal stakeholders, additional hosting environments, and tools like Laravel Shift.
Securing Leadership Support and Stakeholder Buy-in
Getting approval for the upgrade might require you to present a business case. This can be particularly hard when it involves individuals who don’t understand the wider technical impacts. Be sure to highlight the numerous benefits, including a more efficient development team, access to the latest Laravel features, support for newer dependencies, improved performance, and enhanced recruitment prospects (everyone wants to work with up to date tech!). The strongest case lies in the critical need to keep your applications secure as a compromised system could bring your business to a halt – after all, you can’t drive your car if someone has stolen it!
If you need to reference them, there are lists of known cybersecurity vulnerabilities for PHP and Laravel versions that are out of support. Furthermore the security organisation OWASP publishes a list of the Top Ten most critical risks to web application security every 3 years. This list is widely recognised and respected as a foundation for developing secure development practices. Keep in mind that if your company holds security accreditations like Cyber Essentials or ISO27001, it is mandatory to use supported software as part of these schemes. The person responsible for compliance at your company should be able to support your case for performing the necessary upgrade and maintenance work.
Upgrade the Code
With the necessary approvals in place, it’s time to proceed with the actual upgrade. Where possible ahead of time merge signed off feature branches; freeze other development activities and focus on upgrading the application on a dedicated upgrade branch. Hosting a separate instance of the upgraded application for testing purposes is also recommended, allowing critical fixes to be expedited to production with minimal disruption to the upgrade and to facilitate user acceptance testing at the end of the process.
We highly recommend using Laravel Shift to support the upgrade process. Whilst it is possible to manually upgrade a Laravel application and the official documentation will assist somewhat with this; Laravel Shift provides automation to speed up the process as well as signposting issues you may have with your dependencies not just Laravel core. Even if you can’t use Laravel Shift for some reason it’s worth following a similar process to the one they outline: tackling one version at a time; addressing any issues encountered; then proceed to the next version when you’re confident the application is working on that version. Also pause at each LTS (Long-Term Support) version for a thorough manual test of the application to ensure it is still working as expected. Of course you should be running your automated tests with each version bump to ensure they are all still passing and fixing up those that aren’t.
Prioritise Upgrade Goals
While refactoring may seem tempting at this stage, it’s crucial to prioritise the upgrade itself, aiming for efficiency and stability. Make minimal necessary code changes to achieve a stable system that can be tested and rolled out with minimal disruption. Refactoring and code quality improvements can be revisited at a later date. Continually refer to the agreed-upon timelines outlined in your plan, ensuring the ability to deliver a functional upgrade by the end of the designated period.
Testing, Testing, Testing
Testing is of paramount importance throughout the upgrade process. If you have an automated test suite in place, leverage it to the fullest extent possible and supplement it with selective manual testing. Keep in mind that the approach to automated testing changed significantly in Laravel 8.x and you will need to weigh up the pros and cons of migrating an existing test suite to use the modern class based Factory syntax or installing the legacy Factory package to keep using the old approach.
In cases where time constraints prevent the creation of an automated suite, opt for a manual testing approach. Create a detailed test plan in collaboration with users of the application, covering critical features and ensuring consistent testing protocols. This not only helps during the upgrade process but also serves as a reference for future updates and improvements. It can be useful to write a test plan using a Behaviour Driven Development style as this can be translated into automated tests in the future.
Make sure to allocate ample time for testing and bug fixing both before and after the launch!
Summary
In this article we’ve touched on some of the main points to consider when planning and undertaking a Laravel upgrade project, to summarise:
- Research and understand the impact – document issues, estimate timeframes and resources required to complete the upgrade
- Make a case – highlight the importance of a secure application, particularly for accredited compliance
- Gain support – upgrade work needs to be signed off by relevant stakeholders, make sure they are on board
- Make a plan – staying on task and avoiding unnecessary refactoring is crucial to upgrading in a timely manner
- Upgrade in isolation – create a dedicated upgrade branch and freeze other development work so the upgrade is prioritised
- Test – automated and manual testing are crucial to knowing your upgraded application still works as expected
As a Laravel Partner and experienced with using Laravel Shift, if you need support or guidance in your upgrade project, we’re here to help.