Upgrading a PHP project can be challenging and complex. Over the years, I’ve tackled numerous upgrades—sometimes on my own, other times as part of a team. Through these experiences, a clear process has emerged, and today I want to share that with you. My goal is to provide something practical, actionable, and easy to follow.

If you aren’t familiar with the Awareness–understanding matrix, this is a system that helps identify areas where people or systems are aware or unaware of issues and whether they understand or don't understand how to address them. This will be very useful to understand and prioritize risks when upgrading. 

Let’s have a look at at the Awareness–understanding matrix: 

Fantastic! But how is this practically relevant to a PHP upgrade? If we're aware of the risk and understand the problem, we can take proactive steps to mitigate the risk by addressing the issue. This is also a very good way in which to discuss the upgrade with your managers, you can provide a solid and well defined plan that handles the risks. 

Let’s look at a practical example in the context of upgrading: 

This is a very good starting point and the more unknowns we have the more risk there is and therefore, reduced likelihood of having  a successful upgrade.  

The first step is to go through your codebase and figure out how much risk is associated with any potential change. My approach to this is to have a risk assessment for each major version change from the project’s current PHP version to the most recently released version. 

So if you have a PHP 7.2 application, there have been 6 minor versions released since then, so figure approximately out how many knowns and unknowns you have between each version. 

So from 7.2 to 7.3: 

Do this for each version until the most recent version (even if the target version is lower) and this will either show that upgrading is a waste of time and just bin the project and start again or the result will formulate your project upgrade roadmap.

Install the following: 

Figure out how each tool works (out of the scope of this article) and add your findings to a risk assessment of each version. It’s important to not get stuck just collecting data, we now need to start the upgrade and we have enough data based on the project to understand the level of risk associated with each version upgrade, which will also indicate an approximate timeframe and therefore the cost. 

Assuming that the data you found indicates that an upgrade is time effective and worthwhile, the next phase is implementation. 

There are some things we need to set up before beginning the upgrade:

The process of this phrase is of course extremely dependent on the previous step. For example if you find that you don’t have much test coverage, that would be a fantastic place to start. Because if you don’t know it's broken, you can’t fix it. So a lot of the priority will be set by the first step. But the process that I’ve been using for a while now, is to incrementally go up through the versions. 

Sticking with the 7.2 version example, the first thing we need to do is update the composer.json, as we are upgrading to 7.3 we can:

This may chuck out “Your requirements could not be resolved to an installable set of packages.” go through each problem and resolve it manually and run “composer update -W ” again until upgrades. 

Important to note that this might break your entire application and it may no longer work. This should be expected if you have done the first step correctly. 

Ok, so now we have the application on the version we need, now we need to upgrade the broken bits in the project, have a look at what the process might look like. 

Following this iterative process of upgrading should result in a fast and efficient upgrade.

Merge each major version into main / production, avoid having a massive upgrade branch that will be a nightmare to merge into main. Now follow the same process until you reach your desired PHP version. 

The upgrade is nearly complete, but now we need to tie up any loose ends and make sure everything is in order. This phase is all about cleaning up your codebase and ensuring that everything is properly documented, so you—and anyone else working on the project—can understand and maintain it going forward.

By following this process, you’re not only increasing the likelihood of a smooth upgrade but also setting yourself up for long-term success. Clean code and clear documentation will make your life—and the life of anyone else working on the project—much easier moving forward. Good Luck!