Upgrading Legacy to the Latest PHP Version

Your application runs on an old PHP version that is about to go out of support. How to upgrade without breaking the application? You will need the right tools for detecting and fixing those issues, as well as a way to verify that the application is still working correctly. In this presentation, I will share the strategy that I employed when upgrading millions of lines of untested code.

Transcript

1. Anna Filina | June 2025 Upgrading Legacy to the Latest PHP Version
2. “I don't know whether my application will work on the latest PHP.”
3. Typical Legacy App • Millions of lines • PHP 4, 5, 7 • $GLOBALS • Undefines variables • Dead libraries • Removed extensions • No type declarations
4. • Coding since 1997 • PHP, Java, C#, VB, AS, etc. • Principal Engineer @ Zend • Migrating legacy • Writing tests • Teaching developers Anna Filina
6. Agenda • Show open-source tools • Investigate compatibility issues • Tips for fixing issues • Tips for testing a migration
7. • PHP 7.2 - 7.4: ZendPHP • Backporting security patches • Until December 2026 • Can be a pit stop until PHP 8.x Consider Commercial LTS
8. PHPCompatibility Tells us what to fix.
9. • github.com/PHPCompatibility/PHPCompatibility • Follow README to install • Analyzes our code • Detects incompatibilities PHPCompatibility
10. Analyzing Code phpcs -p . --standard=PHPCompatibility --colors --extensions=php,inc,phtml --runtime-set testVersion 8.4
11. Report FILE: /www/src/app/controllers/MyController.php ------------------------------------------------------------------ FOUND 1 ERROR AFFECTING 1 LINE ------------------------------------------------------------------ 166 | ERROR | Using 'break' outside of a loop or switch structure | | is invalid and will throw a fatal error since PHP | | 7.0 ------------------------------------------------------------------
12. • Prioritize errors • Research before fixing • Can't know values at runtime, such as fopen($path) • Most PHP 8 issues will happen at runtime • PHPStan, Psalm, etc. can find potential runtime issues Using the Report
13. • php.net – docs, release notes, migration guides • php-legacy-docs.zend.com – docs for old PHP versions • phplift.com – building my own migration reference • exakat.readthedocs.io – compatibility rulesets • Experimentation • PHP source code (if obscure, undocumented change) Looking for Answers
14. 3v4l.org Runs code in different PHP versions.
15. Common Mistake in Legacy $response = '1234567890'; $header = 'Content-length: ' . strlen($response) + 1; echo $header;
18. Cross-Version Fix $response = '1234567890'; $header = 'Content-length: ' . (strlen($response) + 1); echo $header;
19. Do Your Own Research FILE: /www/src/app/controllers/MyController.php ------------------------------------------------------------------ FOUND 1 WARNING AFFECTING 1 LINE ------------------------------------------------------------------ 166 | WARNING | Function each() is deprecated since PHP 7.2; Use | | a foreach loop instead ------------------------------------------------------------------
20. Foreach is Fine Here while (list($i, $row) = each($result)) { }
21. Foreach is Not Fine Here else if (list(, $opt_arg) = each($args)) { }
22. Returns More Than You Think $key = each($result)['key']; $value = each($result)['value']; $key = each($result)[0]; $value = each($result)[1];
23. Doesn't Only Read $row1 = each($result); $row2 = each($result); // different value
24. function each(array &$array) { if (current($array) === false) { return false; } $key = key($array); $value = current($array); next($array); return [ 1 => $value, 'value' => $value, 0 => $key, 'key' => $key, ]; }
25. mcrypt Multiple solutions.
26. • PECL version: unmaintained since 2023 • Polyfill: mcrypt_compat • Replacements: libsodium or openssl Options
27. PHP phpseclib/mcrypt_compat Polyfill If introducing Composer, auto_prepend_file = bootstrap.php
28. PHP ext-openssl Another Extension Will require many code changes
29. mcrypt.OFB openssl.OFB != If using OFB mode, will need to re-encrypt everything
30. How to test the mcrypt upgrade?
31. Raw data Legacy app Encrypted Raw data Upgraded app Encrypted == == Straightforward in PHPUnit
32. mysql Multiple solutions.
33. ext-mysql ext-mysqli ext-pdo
34. • Connection object needs to be tracked. • Connection object now a mysqli type. • Field metadata represented differently. • Different methods for unbuffered queries. mysql to mysqli not 1:1
35. Hidden Global State mysql_connect('localhost', 'user', 'pass'); mysql_query('SELECT * FROM example'); // vs $connection = mysqli_connect('localhost', 'user', 'pass'); mysqli_query($connection, 'SELECT * FROM example');
36. mysql to mysqli / pdo conversion can't be unit-tested.
37. Cypress, Playwright, ... Characterization tests.
38. npm install cypress
39. npx cypress open
40. • Write tests for legacy • Run tests on legacy branch • Upgrade the code • Run same tests on upgrade branch • All tests pass = done Testing Methodology
41. Write as many tests as you need to be confident.
42. • Criticality: login > pdf receipts • Complexity: login < pdf receipts Prioritize
43. • More black-box tests, fewer white-box • Discover issues using PHPCompatibility • Discover potential issues using PHPStan, Psalm, etc. • Discover the rest based on failed tests • Compare multiple solutions before deciding • Strive for reversible decisions Takeaways
44. • opencollective.com/phpfoundation • github.com/PHPCompatibility/PHPCompatibility • github.com/phpstan/phpstan • 3v4l.org/sponsor • github.com/phpseclib/mcrypt_compat • github.com/jedisct1/libsodium • openssl-foundation.org/donate/ • phpunit.de/sponsors.html Sponsor Your Tools
46. Questions? Anna Filina https://phpc.social/@afilina