How to Check Your Code for PHP Compatibility Before You Upgrade
In this article11 sections
Most failed PHP upgrades fail in ways you could have predicted. The new version removes a function your plugin still calls, tightens a rule that old code broke without anyone noticing, or runs without an extension that was quietly installed on the old setup. These problems are known, documented and findable before you change anything. This guide shows how to check a WordPress site, a Laravel application and custom PHP code for compatibility with a newer PHP version, using free tools, on a copy of the site, so the first time a problem appears is on your screen and not on your customers’.
The checks apply on any platform, from a cPanel account to a VPS, and they are the same whichever way you later switch the version. The platform steps are in the guides linked in each section.
Know what actually changes between versions
PHP’s major-minor releases, such as 8.2, 8.3 and 8.4, follow a regular schedule, and each one deprecates some behaviour and removes behaviour that was deprecated earlier. A deprecation is a warning: the code still works, but it will stop working in a later version. A removal is a break: the code fails. Your job is to find both, and to fix removals before the upgrade and deprecations before the next one.
Typical examples are dynamic properties on classes, which are deprecated in recent versions, passing null to functions that expect a string, implicit conversions between floating point numbers and integers, and old string and array helpers that were removed outright. The official migration guides on php.net list every change by version, and you should read the one for each version between your current one and your target.
Step 1: Make a safe place to test
Never test on the live site. Copy the files and the database into a staging site or a test subdomain, update the copy’s configuration to use the copied database, and block search engines from it. The steps for a WordPress copy are in how to set up a WordPress staging site. Make sure the copy can send no email and charge no card, because tests will click things.
Step 2: Collect the facts
Write down the current PHP version, the target version, and what the site depends on. Over SSH, if you have it:
php -v
php -m | sort > php-modules-before.txt
composer show --direct 2>/dev/null | head -n 40
Expected: the version, a saved extension list, and the direct Composer dependencies of a PHP application. The extension list matters because a missing extension on the new setup is a leading cause of upgrade failures. For WordPress, also list the plugins and themes with their versions:
wp plugin list --fields=name,status,version,update
wp theme list --fields=name,status,version,update
Step 3: Scan the code with PHPCompatibility
The PHPCompatibility ruleset for PHP_CodeSniffer reads your source files and reports code that will not work on the version you name. Install it in the project or in a separate folder, using Composer:
composer require --dev squizlabs/php_codesniffer phpcompatibility/php-compatibility
vendor/bin/phpcs -p . --standard=PHPCompatibility --runtime-set testVersion 8.4- \
--extensions=php --ignore=vendor,node_modules --report=summary
The value 8.4- means 8.4 and later. Expected: a summary with a count of errors and warnings per file. Errors are things that break on that version, and warnings are things that are deprecated or risky. Fix the errors first. For a WordPress site, point the scan at your custom theme and plugins, and not at WordPress core or third-party plugins, because you cannot maintain those, and the scan of a large plugin is slow and noisy.
Scanning finds syntax the new version rejects. It cannot see everything that happens at runtime, so treat it as the first filter, not the only one.
Step 4: Check the dependencies
In a PHP project that uses Composer, the dependency file states which PHP versions each package supports. Ask Composer whether your target version is allowed:
composer why-not php 8.4
composer outdated --direct
Expected: either nothing, which means nothing blocks the version, or a list of packages whose requirements exclude it. For each blocker, check whether a newer release supports the target version. Update that package in the test copy, run the tests, and note any breaking changes in its release notes. A package that is abandoned and does not support the version needs replacing, and that is a project of its own, which is better to know now than after the upgrade.
For a Laravel application, check the framework version against the PHP versions it supports in its upgrade documentation, and update the framework in steps if your target is newer than your version supports.
Step 5: Check WordPress plugins and themes
WordPress plugins publish a Tested up to version for WordPress and, in many cases, a required PHP version in the plugin’s readme. Check the plugin page for each active plugin and note any that were last updated more than a year ago. A plugin that has had no update for a year is a risk on its own, and it is the most likely to break on a new PHP. Remove plugins you do not use. For the ones you keep, update them first, on the copy, and then change the PHP version.
Open Tools > Site Health in the dashboard. It reports the PHP version, any required modules that are missing, and recommended settings. Fix what it flags before the change. The wider habit of keeping updates under control is in how to set up WordPress automatic updates safely.
Step 6: Run the copy on the new version with errors visible
Switch the test copy to the target PHP version, using the steps for your platform: cPanel, Plesk, Ubuntu with Nginx, Ubuntu with Apache, AlmaLinux and Rocky, IIS on Windows, or Docker. On the copy only, show all errors, so you see deprecations that would be hidden on a live site. For WordPress, set these in wp-config.php of the copy:
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
Then use the site as a visitor and as an administrator, and read wp-content/debug.log afterwards. For other applications, set error_reporting to E_ALL and log to a file.
Step 7: Walk through the pages that earn money
Make a short checklist of the paths that matter, and click each of them on the copy: the home page, a post and a category page, search, the login, the contact form, any member area, and for a shop the product page, the cart and a test checkout in sandbox mode. Run the application’s automated tests too, if it has them. Record each failure with the exact error line from the log.
Step 8: Decide, fix and repeat
Sort what you found into three groups. Blocks are errors that stop the site, and they must be fixed before the upgrade. Deprecations are warnings that you can schedule, ordered by how soon the next PHP version removes them. Noise comes from code you do not control, which you track but do not fix. Fix the blocks on the copy, run the checks again, and only then plan the live upgrade for a quiet hour, with a backup and a rollback. The errors you are likely to meet, with fixes, are collected in how to fix common errors after a PHP upgrade.
Common mistakes
- Testing on the live site. The first failure is then a customer’s.
- Trusting one scan. Static analysis misses runtime problems. Use the scan, the tests and a click-through.
- Ignoring extensions. A missing extension breaks the site faster than any syntax change.
- Jumping several versions. Move one version at a time, and test between each step.
- Leaving unmaintained plugins. They are the most likely to fail and the least likely to be fixed.
Frequently asked questions
How long does a compatibility check take?
For a small WordPress site, an afternoon. For a large custom application, days. Most of the time goes into fixing what you find, not into finding it.
Can I skip the check if I only move one minor version?
A minor step is lower risk, but it can still remove something your code uses. A short scan and a click-through take little time and are worth it.
Is a deprecation warning something I must fix now?
Not before this upgrade, but it is the list of problems for the next one. Fix them over time, starting with the code you wrote.
What if a plugin is not compatible?
Look for an update, find an alternative, or ask the author. As a last resort, stay on the older PHP version for that site only, and plan a replacement, because the older version stops receiving security fixes.
A PHP upgrade is predictable if you look first. Make a safe copy, collect the facts, scan with PHPCompatibility, check the dependencies and plugins, run the copy on the new version with errors visible, and walk through the pages that matter. Fix the blocks, schedule the deprecations, and only then upgrade the live site. For help choosing the version itself, read which PHP version to use: support dates and an upgrade plan.
Want this done for you? If you would rather have an engineer plan and carry out the work on your own site, you can hire the author through the Upwork profile of Munaf Sheikh.