PHP Version Migration: Compatibility Testing, Multiple Versions and Rollback

Compatibility scanning for a PHP upgrade, running PHP-FPM versions separately, gradual migration and a tested rollback plan.
Technical summary
Technology
PHP 8.x, PHP-FPM, PHP_CodeSniffer, PHPCompatibility, Nginx, Apache, WP-CLI
Topic
Compatibility and planning for a major PHP version migration
Level
Intermediate–advanced
Prerequisites
  • Knowledge of Linux package management and PHP-FPM
  • Basic use of Composer
  • Access to a staging environment
In this article7 sections

Changing the PHP version from the panel takes two seconds. Afterwards, it sometimes takes days to notice that an old custom plugin, a theme function or a cron script that runs at night is throwing a fatal error, because only one part of the site quietly stops working. That’s why we treat a major version migration not as a settings change but as a job made up of compatibility analysis, a gradual transition with multiple versions and a written rollback plan. The steps below are for system administrators and developers managing WordPress and custom PHP applications.

Why keep the PHP version up to date

Each major PHP branch has a period of active support followed by security fixes only; once that period ends, no official security patches are released for the branch. Current dates are published on php.net’s supported versions page; plan according to that page.

An often overlooked detail: distributions such as Debian, Ubuntu LTS and RHEL can backport security patches to the PHP packages in their own repositories for the duration of the distribution’s support. So a version number that appears out of support on php.net may still be receiving patches as long as the distribution’s security support continues. Don’t expect this backporting for versions installed from third-party repositories (e.g. Ondřej Surý’s repositories for Debian/Ubuntu, the Remi repository for RHEL-based systems). First look at where the package comes from. Then decide.

The reason beyond security is the dependency chain: WordPress core, plugins and Composer dependencies drop support for old PHP versions over time. A site that stays on old PHP eventually can’t even install the plugin version containing a security fix. Plan this chain together with your WordPress update policy.

Compatibility analysis and static scanning

The goal is to answer the question “which code will break on the new version?” as precisely as possible before the migration. Two complementary methods are used: static scanning and runtime observation. Neither replaces the other.

Inventory

First take an inventory of the code to scan: custom themes and plugins, mu-plugins, cron scripts on the server, libraries pulled in with Composer. The item most often forgotten in the field is single-file PHP scripts someone left in /root or a home directory years ago and that are called from crontab. For public plugins, the first check is whether the current version states support for the target PHP version and whether it’s actively maintained; a plugin that hasn’t been updated for a long time is risky regardless of the scan result. We described how to keep a plugin inventory in the article on WordPress plugin selection and inventory management.

Scanning with PHPCompatibility

PHPCompatibility is a ruleset written for PHP_CodeSniffer; it looks for constructs in the code that have been removed or whose behavior has changed in the target version. For WordPress projects, there’s the PHPCompatibilityWP package, which takes WordPress’s own compatibility layers into account:

composer require --dev phpcompatibility/phpcompatibility-wp:"*"

vendor/bin/phpcs -p wp-content/themes/corporate-theme \
    wp-content/plugins/custom-plugin \
    --standard=PHPCompatibilityWP \
    --runtime-set testVersion 8.3- \
    --extensions=php \
    --report=summary

testVersion 8.3- checks whether the code is compatible with PHP 8.3 and later. An important limitation: the PHP versions PHPCompatibility covers depend on the PHPCompatibility version you use. The 9.x series, which remained the stable line for a long time, mainly checks changes up to PHP 7.4; PHP 8.x checks come with the 10.x line. Check on the project page whether the version you installed covers the target PHP changes. If it doesn’t, a “clean” result is misleading.

Static scanning can’t catch errors that depend on variable types; whether null will reach a function at runtime can’t always be seen from the code. The second step is to run the application with the new version in a test environment and log the errors:

; staging php.ini (or php_admin_value in the pool configuration)
error_reporting = E_ALL
display_errors  = Off
log_errors      = On
error_log       = /var/log/php/staging-php83.log

Then run the critical flows (form submission, orders, search, admin panel operations, import/export) by hand or with automated tests and read the log. Deprecated warnings don’t break anything today; but they’re the list of points that will turn into errors in the next major version.

Common incompatibilities

Most problems that come up when moving from PHP 7.x to 8.x fall into a few groups. The table isn’t complete; for each major version, rely on the migration sections of the php.net manual.

Version Change Typical symptom
8.0 each() and create_function() removed Fatal error in an old theme/plugin
8.0 Many warnings turned into TypeError/ValueError exceptions (e.g. count() on a non-countable value) Code that previously passed with a warning stops
8.0 Comparison between numbers and non-numeric strings changed (0 == "abc" is now false) Silent logic differences in conditions
8.1 Passing null to non-nullable parameters of built-in functions is deprecated Heavy Deprecated warnings in logs
8.2 Creating dynamic properties (undefined properties) is deprecated Deprecated warnings in old classes
8.4 Implicitly nullable parameter types are deprecated Warnings on typed parameters whose default is null

The number–string comparison is the most insidious. It doesn’t throw an error; only the result of the condition changes. Static scanning can’t always flag these lines. Review form validation, authorization checks and price calculation code that uses loose comparison (==) by hand.

Another source of incompatibility is the server itself. PHP extensions (mbstring, intl, gd, imagick, redis, etc.) must be installed separately for the new version; custom php.ini settings must be carried over to the new version’s configuration directory. Don’t copy the old file as is; carry over only the changed values, so the new version’s defaults are preserved. A missing module is one of the most common causes of the “the site shows a white screen” complaint, and it’s visible with a single command:

# Difference in installed modules between two versions
diff <(php8.1 -m | sort) <(php8.3 -m | sort)

Multiple PHP versions on the same server

In PHP-FPM, each version runs as a separate service and opens its own socket. This lets you move sites to the new version one by one on the same server. The common setup on Debian/Ubuntu:

apt install php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml \
            php8.3-curl php8.3-gd php8.3-intl php8.3-zip

systemctl status php8.1-fpm php8.3-fpm
ls /run/php/
# php8.1-fpm.sock  php8.3-fpm.sock

The version per site is determined by which socket the web server passes PHP requests to. In Nginx, fastcgi_pass unix:/run/php/php8.3-fpm.sock; is used in the relevant server block; in Apache, this definition with mod_proxy_fcgi:

<FilesMatch \.php$>
    SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"
</FilesMatch>

Defining a separate pool for each site with its own user and socket is the cleanest structure for both isolation and version migration. Panels such as Virtualmin manage these pools per site; we described this setup in the article on multi-site server management with Virtualmin.

Gradual migration and testing

On a server with several corporate websites, order the migration from the lowest-risk site to the most critical. The flow is the same for each site:

  1. Scan: Custom code is scanned with PHPCompatibility and the findings are fixed; public plugins are brought up to their current version.
  2. Test environment trial: The site is run with the new PHP version in a test environment equivalent to production; critical flows are tested and the error log is examined.
  3. Backup: A file and database backup is taken immediately before the migration.
  4. Switchover: The site’s socket or pool is switched to the new version, and the web server and PHP-FPM are reloaded. Reload, not restart; let current requests complete.
  5. Verification: Verify the active version not with a temporary file containing phpinfo() but with a screen that shows the version running over the web (in WordPress, Tools > Site Health > Info > Server). wp --info shows the command-line version, so it isn’t suitable for this check; and don’t leave temporary test files on the server.
  6. Observation: The error log, 5xx rate and response time are monitored in the first hours and days. Cron jobs that run weekly or monthly are checked separately on their first run.

Check the OPcache settings too: if the opcache.memory_consumption and opcache.max_accelerated_files values in the new version’s configuration directory (e.g. /etc/php/8.3/fpm/conf.d/ on Debian/Ubuntu) aren’t the same as in the old version, a performance drop after migration is mistaken for an incompatibility and the fault is looked for in the wrong place.

Rollback plan and monitoring

The biggest gain of the multi-version setup is how simple rollback is. As long as the old version’s FPM service is running, switching the site’s socket back to the old version and reloading gives a rollback in seconds. So don’t remove the old version’s packages until the observation period after the last site migration has ended.

But rollback only reverts the PHP side. If a plugin or application version was also upgraded along with the migration and that version changed the database schema, going back to the old PHP version doesn’t bring back the old plugin version. Don’t put the PHP migration in the same maintenance window as plugin and core updates. One variable per window.

Write down the rollback criteria from the start: which type of error (a fatal error, a failure in a critical flow) triggers an immediate rollback, and which (Deprecated warnings) is resolved with an in-place fix. When the observation period ends, stop the old version’s service, remove the packages and update the server inventory.

On servers with several sites, we plan and carry out PHP migrations as part of Linux VPS and Virtualmin management; on WordPress sites, we track plugin and theme compatibility together with the WordPress security, updates and maintenance process. For old applications whose list of incompatibilities is very long, considering the modernization option may be more sustainable than continuing to patch.

Frequently asked questions

If a PHPCompatibility scan comes back clean, is the migration safe?

No. A clean result only shows there are no problems that can be detected statically. Null values arriving at runtime, loose comparisons whose result changes and dynamic calls may not show up in the scan. You need to run critical flows in a test environment with E_ALL error reporting.

Do Deprecated warnings break the site?

No; the code keeps running. But these warnings show that the construct in question may be removed in a future major version, and they can generate a lot of log entries. display_errors should be off in production; log the warnings and fix them in the next development cycle.

How many PHP versions can I run on the same server?

Since each version is a separate PHP-FPM service, technically several can run together. In practice, updating, installing extensions for and monitoring each version is a separate workload; keep the number of versions to a minimum outside the transition period.

Why does WP-CLI show the old version after changing the PHP version on a WordPress site?

WP-CLI runs not from the web server but from the default php binary on the command line. To use the new version per site, run WP-CLI with an explicit PHP path, as in /usr/bin/php8.3 /usr/local/bin/wp, or deliberately change the system’s default php version.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles