Upgrading the PHP version without breaking the website

Use this skill when a website runs on an unsupported branch (5.x, 7.x, 8.0 or 8.1) or when a security patch does not reach its branch. The idea is to demonstrate locally that the website works the same on the target version and then change it in production in a reversible way.

Choose as the target the highest supported branch that the application accepts. For WordPress, check the recommended PHP version for its core and the compatibility declared by each plugin and theme.

1. Inventory

• Current version and SAPI: mod_php, FPM, LSAPI or CGI.
• Extensions in use (php -m) and whether they exist in the target version. Some disappear or move to PECL: mcrypt in 7.2, imap, pspell and oci8 in 8.4.
• The website's own limits: memory_limit, upload_max_filesize, post_max_size, max_execution_time and max_input_vars. Panels may store them per domain or per version; check which values are actually inherited when changing. On a server without a panel, the new version's default values may be different.
• Own code versus third-party code. Updated plugins and themes usually work; own code and abandoned plugins are where errors appear.

2. Isolated local copy

1. Prepare a private copy of the code and a sanitized test database, with credentials different from production. Include representative test media if the flows need them; omit caches and unnecessary personal data.

2. Bring up two environments with official images (php:X.Y-apache or wordpress:phpX.Y-apache, plus mariadb or mysql): one with the current version and another with the target one.

3. Put them on a --internal Docker network, with no Internet access, and publish the ports only on 127.0.0.1. Disable real email sending, integrations and automatic tasks; use local mock services. Do not connect the copy to the production database.

4. In WordPress, create a test configuration:

   • local database;
   • WP_HOME with the real domain, resolved as a network alias to the container;
   • WP_DEBUG_LOG, FS_METHOD=direct, AUTOMATIC_UPDATER_DISABLED, DISABLE_WP_CRON and WP_HTTP_BLOCK_EXTERNAL.

   Without FS_METHOD=direct, WordPress may try to update over FTP and produce errors unrelated to PHP.

5. Give read permissions to the web server inside the container. A widespread 403 is usually due to permissions on the copy.

3. Static analysis by difference

Run PHPCompatibility (or PHPCompatibilityWP) twice, with --runtime-set testVersion <destino> and with the current version, and keep only what appears in the target one. Review separately the problems that already exist: do not discard a finding just because it appears in both environments. The comparison avoids confusing regressions with conditional uses, such as the conditional use of mcrypt or mysql_ in backup plugins.

4. Functional test on both versions

• Go through the home page, the pages linked from it, the search, the login (GET and POST), the REST API, the sitemap and a nonexistent URL.
• Run the administration code: with wp-cli, list the active plugins and run admin_init. Do the same with scheduled tasks and custom forms.
• Compare the HTTP codes and the error log between the two versions. Distinguish new regressions from previous failures. A previous security failure or one in a critical flow can also prevent deployment.
• Delete the copies when finished, because they contain data.

5. Code-breaking changes, by jump

Jump	What to review
5.x → 7.0	mysql_* and ereg* disappear, the /e modifier of preg_replace and the <% / <script language="php"> tags. Many fatal errors become catchable Error. The uniform variable syntax changes ($$a['b']). Constructors named after the class become deprecated
7.0 → 7.4	mcrypt disappears in 7.2. each() and create_function() become deprecated. Braces for accessing characters ($s{0}) and the (real) cast become deprecated in 7.4
7.4 → 8.0	The comparison between strings and numbers changes ("abc" == 0 is false). Many notices become TypeError or ValueError. each(), create_function(), money_format() and track_errors disappear. @ no longer hides fatal errors. Required parameters after optional ones become deprecated
8.0 → 8.1	Passing null to non-nullable parameters of internal functions becomes deprecated. "Tentative" return types appear in internal classes. Serializable without __serialize also becomes deprecated
8.1 → 8.2	Dynamic properties become deprecated, as do utf8_encode()/utf8_decode() and ${var} interpolation
8.2 → 8.3	Few incompatible changes. Review the deprecations in the official migration guide
8.3 → 8.4	Implicit nullable types (Type $x = null) become deprecated. E_STRICT becomes deprecated. imap, pspell and oci8 leave the core
8.4 → 8.5	Consult the official migration guide on php.net before jumping

6. Change in production

• With a panel: change the version of one domain at a time. First check the scope of the selector and the rollback procedure: it may affect several domains or require restarting workers.
  • cPanel: MultiPHP Manager.
  • Plesk: plesk bin site --update <dominio> -php_handler_id <handler>.
  • DirectAdmin: per-domain PHP selector.
  • CloudLinux: PHP Selector.
• Without a panel:
  1. Install the new branch in parallel (phpX.Y-fpm), with its own pool and the same extensions.
  2. Point the website's SetHandler or fastcgi_pass to the new socket and reload the web server.
  3. To roll back, restore the previous socket.
• Before and after each change: the status of the website and key pages, the domain's error log and 5xx errors. Monitor for at least 30 minutes.
• Order: test websites first, then production ones.
• Rollback: also define how to handle writes and schema changes. If the previous version has a known vulnerability, do not restore its public exposure without a containment measure.
• When finished: keep the security mitigation in force applied also in the new version, and record the version of each website and how to roll back.

References

• Supported PHP branches.
• Official migration guides.
• PHPCompatibility.