PHP Version Upgrade
Migrate a website to a supported PHP branch with isolated environments, functional comparison, and rollback plan.
- Updated:
- Words:
- 1067
- Weekly downloads:
- 0
- Total downloads:
- 0
Related links
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:mcryptin 7.2,imap,pspellandoci8in 8.4. - The website's own limits:
memory_limit,upload_max_filesize,post_max_size,max_execution_timeandmax_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
-
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.
-
Bring up two environments with official images (
php:X.Y-apacheorwordpress:phpX.Y-apache, plusmariadbormysql): one with the current version and another with the target one. -
Put them on a
--internalDocker network, with no Internet access, and publish the ports only on127.0.0.1. Disable real email sending, integrations and automatic tasks; use local mock services. Do not connect the copy to the production database. -
In WordPress, create a test configuration:
- local database;
WP_HOMEwith the real domain, resolved as a network alias to the container;WP_DEBUG_LOG,FS_METHOD=direct,AUTOMATIC_UPDATER_DISABLED,DISABLE_WP_CRONandWP_HTTP_BLOCK_EXTERNAL.
Without
FS_METHOD=direct, WordPress may try to update over FTP and produce errors unrelated to PHP. -
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 runadmin_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:
- Install the new branch in parallel (
phpX.Y-fpm), with its own pool and the same extensions. - Point the website's
SetHandlerorfastcgi_passto the new socket and reload the web server. - To roll back, restore the previous socket.
- Install the new branch in parallel (
- 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
Versions (1)
| Version | Downloads (weekly) | Downloads (total) | Published |
|---|---|---|---|
0.1.0latest First release reviewed with official sources and runtime verification. | 0 | 0 | October 21, 2026 |