Safe PHP Upgrades for WordPress: The developer’s guide to fixing deprecated code

Upgrading PHP wasn’t a topic for WordPress developers for a long time. This has to do with the WordPress project’s approach to PHP. Much like with the features in Core, the approach was to stay backward-compatible as long as possible.

Indeed, WordPress dropped support for PHP 5.6 on 8 August 2023. Over four and a half years after PHP dropped support for PHP 5.

As WordPress continued to run on unsupported versions of PHP for a long time, there was little incentive to upgrade. However, hosting providers no longer want to be burdened with maintaining web servers running ancient and insecure software. And they are pushing customers towards upgrading.

This poses challenges for freelancers and agencies maintaining WordPress websites. While PHP upgrades can be smooth and painless, they can also be challenging.

This article is a guide to help you upgrade your client’s websites to a supported version of PHP.

• Why upgrading PHP versions matters–especially for developers
• What version of PHP should I use for WordPress?
• Preparing for a PHP upgrade
• How to check PHP compatibility
• Identifying and fixing PHP issues
• Getting client sign-off: preparing the staging site
• An 8-step process to upgrade PHP on the production website
• Dealing with the worst-case scenario
• That’s all about PHP upgrades for WordPress!

Why upgrading PHP versions matters–especially for developers

The official WordPress.org documentation on PHP updates lists two reasons for upgrading:

1. Improved security: This is a big one. Even if WordPress and all themes and plugins are secure, they don’t protect against vulnerabilities in PHP itself.
2. Improved speed: Each version of PHP includes speed improvements without changing any code. Any speed gain you get for free is welcome.

But that’s for everybody using WordPress. As developers, we have two more excellent reasons to update:

1. New language features: Every new PHP version introduces new language features. And using these can make your code more resilient and elegant.
2. Tooling support: Even a project as big as WordPress only represents a small part of the entire PHP ecosystem. Indeed, according to W3Techs, over 75% of the websites they track use PHP.
   
   All PHP-related tools, such as the Composer package manager, the PHPUnit testing framework, and many others, drop support for old PHP versions at the same speed as PHP itself.

The pain of not updating is something that the WordPress project itself has faced. The Core contributors needed to spend a lot of time implementing workarounds. Just to get these crucial tools to work with all PHP versions supported by WordPress.

What version of PHP should I use for WordPress?

“What version of PHP should I use for WordPress?” is a common question. It depends on two aspects:

1. The support offered by PHP for specific versions.
2. The compatibility of WordPress with PHP versions.

Understanding PHP versioning and backward-compatibility

The PHP project uses semantic versioning. Meaning three numbers represent each PHP version: major.minor.patch. For example 8.2.25.

The changes to these numbers represent the level of backward-compatibility offered by each version:

• Major versions are marked by changes to the first digit, which represent backward-incompatible changes (e.g., from 7.x to 8.x).
• Minor versions change the second digit (e.g., from 8.0 to 8.1) introduce backward-compatible new features or enhancements to existing functionality.
• Patch versions changes to the third digit (e.g., from 8.1.1 to 8.1.2) are for bug fixes or security patches that do not affect the API or behavior of the language.

Features that are planned for removal are first deprecated in a minor version. They are then removed in a following major version. This provides developers with time to update their code.

Understanding the PHP support process

Whenever the PHP project releases a new version of the PHP language, it goes through three phases:

1. Active support (around 2 years): During the first two years, each version receives regular updates. These include improvements, bug fixes, and security patches.
2. Security support (usually 1 year): Only security vulnerabilities are fixed once active support has ended.
3. End of life: After three years of support, a PHP version receives no updates.

This is an overview of the currently supported PHP versions:

Branch	Initial Release	Active Support Until	Security Support Until
8.1	25 Nov 2021	25 Nov 2023	31 Dec 2025
8.2	8 Dec 2022	31 Dec 2024	31 Dec 2026
8.3	23 Nov 2023	31 Dec 2025	31 Dec 2027

By looking at this table, we can see that your websites should run at least PHP 8.1, but it is recommended that you run PHP 8.3.

Understanding WordPress PHP support policy

WordPress uses a simple versioning approach. Every release is a major version and version numbers increase sequentially.

So 5.9 follows 5.8, and 6.0 follows 5.9. The severity of changes between 5.9 and 6.0 is the same, and there are also no links between the WordPress and PHP versions.

WordPress supports a range of PHP versions. An overview of these, with a support chart is available in the developer documentation.

Currently PHP 7.4 is the required PHP version for WordPress 6.3 and higher.

When it comes to the most recent PHP versions:

• WordPress 6.6 supports for PHP 8.2 with exceptions.
• WordPress 6.7 has beta support for PHP 8.3.

So, what do these terms mean?

• With exceptions means that WordPress is fully compatible except a few parts. This is because WordPress has to support lots of different server configurations. So the solutions are not straightforward.
• Beta support means that WordPress runs without issues. But you’ll see deprecation notices coming from Core in the logs.

Recommendations for PHP versions

My recommendation is to run a PHP version that has active support from the PHP project and full support in WordPress.

Which currently means PHP 8.2.

But if you don’t mind a bit of noise in the PHP logs, I’d recommend using PHP 8.3. At least on your local development environment and on staging sites.

Which brings us to the next point: Actually performance a PHP upgrade.

Preparing for a PHP upgrade

Before we do anything, we must ensure that we have everything set up that we need.

Back up all website code in source control

Using a source control tool like Github is the equivalent of doing backups. You want a snapshot of all the code that runs the website.

This includes, of course, any custom code as well as all third-party free and paid plugins and themes.

All plugins available from WordPress.org, as well as most premium plugins, support installing them through Composer. This prevents you from having to track all of their code in Github, keeping the repository as lean as possible.

Set up local

You should set up a local development environment. This is where you’ll do all of the testing and potentially fix code.

A standard option for a WordPress local development environment is LocalWP. But as usual, if you are using something else and are happy–then keep using that.

You should have all the code that runs in production on your local machine. In addition, you should import the database from production. You don’t necessarily need everything in the uploads directory. If it’s massive, a subset of data is enough.

Ensure error logging is enabled

In your wp-config.php, ensure that:

1. WP_DEBUG is set to true.
2. WP_DEBUG_LOG is set to true.

This will ensure that all PHP issues are logged for you to examine. I also recommend using a debugging plugin like Query Monitor.

Consult the official PHP documentation

The PHP website has an upgrade guide for each PHP version. Now is the time to read up on the changes that the version you’ll upgrade to brings.

Keep in mind that when upgrading from several versions, you’ll need to consult the guides for the skipped version as well. So, when upgrading from 7.4 to 8.2, you’ll need to consult the 8.0, 8.1, and 8.2 guides.

There are two important sections in each guide:

• Backward-incompatible changes: These will result in fatal errors. Issues that stop PHP execution will break the website.
• Deprecations: Deprecated code will not break the website. But it will output a deprecation notice.

With this tooling setup, you know you are ready to perform the actual update work.

How to check PHP compatibility

You have three tools at your disposal to check your PHP code for compatibility issues:

1. Static code analysis.
2. Automated testing.
3. Manual testing.

Static code analysis

When it comes to analyzing code, you can either use:

• Dynamic analysis: This runs the code to find issues.
• Static analysis: This looks at the source code and tries to find issues based on that.

Static analysis is easier to set up and run. But because it just looks at code and doesn’t run it, this can lead to false positives. This means that code is getting flagged by the tool that, in reality, doesn’t pose any issues.

So, while it’s not a perfect process, static code analysis is still the first tool to reach for.

The primary tool to use here is the PHP Compatibility Checker. It is a collection of “sniffs” that check your code for compatibility with higher PHP versions. It is built upon the PHP CodeSniffer tool that WordPress also uses for its coding standards.

There’s also a more specialized variant for WordPress, PHPCompatibilityWP. It is aware of the cross-version PHP support in WordPress and can prevent false positives.

Now you might not want to set this tooling up. If that is the case, you can try the PHP Compatibility Checker plugin. I’m mentioning the plugin because it was a good option in the past. I am not sure about its current maintenance status, so use with care.

Finally, you might not need to set up any tooling at all. Certain hosts offer tooling built into their management dashboards to check compatibility. You can also request a check from support.

Automated testing

If you have written PHP unit tests for your custom code, they are the best tool for detecting issues in your code.

I am aware that while unit testing is the default in the wider web ecosystem, it’s still not too common among WordPress developers.

But if you are writing any complex PHP code or even a lot of custom code, you should definitely start using automated testing.

You can check out my WordPress unit testing course to learn more.

Manual testing

Even with all the automated tooling, manual tests will always be part of the procedure.

Ideally, you have a written testing procedure for the website. If this is not the case, now is the best opportunity to create one:

1. Identify the key features and functionality that need testing. This includes individual pages such as the homepage, product or service pages, etc. But it also extends to interactive elements such as forms or e-commerce features.
2. For the pages, list their URL and the key elements to look for.
3. For interactive features, create simple 1-2-3 instructions that go through every step. Make sure to have dummy test data and accounts handy.
4. Organize the tests by priority, with the critical functionalities coming first.

Identifying and fixing PHP issues

You now have a bunch of potential issues to look at, and fix. Of course we’ll go through by severity.

Triaging issues

First, we’ll review any feedback we get from running the code. So, from the automated tests and the manual tests:

1. We’ll start with the fatal errors.
2. Next come warnings.
3. Last are notices.

Second, we’ll look at any feedback from analyzing the code.

How to fix issues

The fix for an issue depends on who owns the code:

1. For premium plugins and themes, reach out to support. If you provide a complete bug report, they should be able to help you quickly.
2. You can try the support forum on WordPress.org for free plugins and themes. Unfortunately, many free plugins don’t offer active support or fixes.
3. For your code, it’s, of course, up to you to fix it.

In reality, especially with free plugins and themes, you’ll have to fix the code yourself.

Forking and fixing

To fix third-party code, you “fork” it. This means you’ll create a version of the code that is detached from its original and will not receive any further updates from it.

To do this:

1. Set the Update URI (in the plugin or theme) to false. This prevents future updates of the code from WordPress.org.
2. Add the original code to source control. You always want to have a way to undo your changes.

When working with third-party code, it can be difficult to determine whether your changes introduce any unwanted side effects.

So, make sure to include testing instructions in your manual testing procedure to cover the functionality affected by these changes.

I’ve also removed code rather than fixed it in the past. An example might be a plugin with issues in its custom widget code. If your website is not using these widgets, then it’s a lot faster to remove this code rather than fix it.

Getting client sign-off: preparing the staging site

So far, all of the changes have been made to your local environment. And the only person testing was you.

The next step is to create a staging site. This is a copy of the live website that allows you to test changes without affecting the live site.

Most hosting providers offer the possibility to create a staging copy of the production website with a few clicks.

Once the site is up, make sure to change all relevant data that would impact the real users of the website.

A simple example would be a social sharing plugin that publishes new posts to social platforms. You don’t want to spam social accounts with test data.

If you have forms on the website or any other email functionality, you can use the Disable Emails and Email Log plugins. This will prevent emails from being sent while still allowing you to see their contents.

You can use the Error Log Monitor plugin if your host doesn’t provide a good interface for the PHP logs. Just prevent public access to the error logs using an .htaccess or ngnix config file. Exposing logs publicly is a security risk.

With the website prepared, perform the necessary steps from the next section. This is the “real world” test of your work and preparation for the production upgrade.

The final step is to inform the client about the update and invite them to test it themselves. Do this even if your clients never test their websites.

You want to:

• Let them know about the update and why it is important. This will reinforce your image as a web professional.
• Detail all the testing you have done and share the manual testing procedure. This can help them perform their testing.
• Ask them for a sign-off. This is the crucial part. Even though you are a developer, you cannot know everything about their website. It’s their responsibility to sign off on your work. That way if something still breaks, they are as much at fault as you.

An 8-step process to upgrade PHP on the production website

Step 1: Perform a backup

As before any significant intervention, perform a backup. This should include:

• The database.
• The uploads directory.
• All code.

Step 2: Put the website into maintenance mode

While you are doing the upgrade, you want to restrict public access to the website. WordPress supports this through the wp-content/maintenance.php drop in.

However I do prefer the Maintenance Mode plugin by WordPress VIP. It allows the public website to show a maintenance message. But logged-in users with a specific role can still access every part of the website.

Step 3: Upgrade PHP

Use the administration panel provided by your hosting provider to upgrade the PHP version.

Once the process is complete, visit the WordPress admin. Go to Tools > Site Health and double-check that the WordPress version shown here matches that from your host.

Step 4: Perform any code updates

Transfer any code that needed fixing to the web server.

If your host uses a full-page cache, ensure that you purge it at this point. You don’t want any stale pages around. Also, make sure to clear the object cache.

Step 5: Manual testing

Perform all manual tests using the procedure you created while preparing for the upgrade.

Step 6: Check the logs

Look at the PHP logs for anything that looks off. The logs might not be clean, but there shouldn’t be any red flags.

Step 7: Disable maintenance mode

If everything looks OK, disable the maintenance mode.

Step 8: Post-upgrade monitoring

The real test only comes once the website is public again and receives real traffic.

You should periodically check in and review logs to detect any issues that weren’t caught in your own testing.

On websites with a lot of traffic, keeping an eye on them for a few hours is enough. For low-traffic sites, check in every day for a few days.

Dealing with the worst-case scenario

So, you’ve upgraded production, and the worst happens: Fatal errors. Broken pages. Features not working.

And maybe you’re getting angry phone calls or emails from your client.

I know it’s simple to say but difficult to do: don’t panic.

This is software engineering, and mistakes do happen. I have broken my fair share of websites, among them a bunch of heavy-traffic websites.

If you read upgrade guides meant for end users, the solution will to downgrade again. But you are not an end user. Your upgrade process isn’t to hit “update” and hope for the best.

All the steps we have taken so far aim to eliminate the possibility of the worst happening. But if it still happens, treat it like any other bug and fix it.

It’s better to keep the situation as is and fail forward rather than downgrade and go through the same process again. You’ll find that many fatal errors can be fixed quickly and with minimal effort.

If this doesn’t happen to be the case, and you are spending a long period on unsuccessfully trying to fix the website, then downgrade. But make it a last resort rather than the default response.

That’s all about PHP upgrades for WordPress!

There you have it—my process for smooth and safe PHP upgrades. My goal was to be as complete as possible and provide a step-by-step process for you to follow along.

If you enjoyed this article, please subscribe to my newsletter below. I send out content like this every week.