{"id":112,"date":"2026-11-02T16:00:00","date_gmt":"2026-11-02T15:00:00","guid":{"rendered":"https:\/\/hoja.in\/blog\/finding-php-8-fatal-errors-in-legacy-code-before-production\/"},"modified":"2026-10-16T14:00:13","modified_gmt":"2026-10-16T12:00:13","slug":"finding-php-8-fatal-errors-in-legacy-code-before-production","status":"publish","type":"post","link":"https:\/\/hoja.in\/blog\/finding-php-8-fatal-errors-in-legacy-code-before-production\/","title":{"rendered":"Finding PHP 8 fatal errors in legacy code before production"},"content":{"rendered":"

The short version of the story: the child theme of my old blog passed a comment callback as 'callback' => mytheme_comment<\/code>, without quotes. On PHP 7 that was a warning and the string \"mytheme_comment\"<\/code>. On PHP 8 it is a fatal Error<\/code>, and every blog post with comments died. I told the full story in an earlier post. This one is about the question that came after: which tool would have told me before<\/em> the deploy?<\/p>\n

I did not want to answer from memory, so I ran the tools against a minimal example and against the real old comments.php<\/code> from git. Versions: PHP 8.4 CLI, PHPStan 2.3.1, PHP_CodeSniffer 3.13 with PHPCompatibility 9.3.5 and 10.0.0-alpha2.<\/p>\n

The bug in ten lines<\/h2>\n
<?php\nfunction mytheme_comment($comment, $args, $depth) { echo 'x'; }\n\nfunction render_list(): void {\n    $options = array(\n        'style'    => 'ol',\n        'callback' => mytheme_comment,\n    );\n    var_dump($options['callback']);\n}\nrender_list();<\/code><\/pre>\n
PHP 7.4 prints Warning: Use of undefined constant mytheme_comment - assumed 'mytheme_comment' (this will throw an Error in a future version of PHP)<\/code> and carries on. PHP 8.4 prints Fatal error: Uncaught Error: Undefined constant \"mytheme_comment\"<\/code>. The future arrived.<\/p>\n
php -l: only syntax, and only for the PHP you run it with<\/h2>\n
$ php -l src\/comments.php\nNo syntax errors detected in src\/comments.php<\/code><\/pre>\n
That is correct: it is valid syntax. A bare word is a constant lookup, and whether that constant exists is only known at runtime. php -l<\/code> on the real old comments.php<\/code> said the same. So the linter is not useless, it just answers a different question.<\/p>\n
Where php -l<\/code> does help: syntax that PHP 8 removed. The old string offset with curly braces is a parse error now:<\/p>\n
$ php -l syntax\/curly.php     # contains: echo $s{0};\nParse error: syntax error, unexpected token \"{\", expecting \",\" or \";\" in syntax\/curly.php on line 3<\/code><\/pre>\n
The important detail: run the linter with the target<\/em> PHP version. php -l<\/code> on your old PHP 7.x server will happily accept that file. In DDEV that is easy, set the target version and lint everything once:<\/p>\n
ddev exec 'find public\/blog\/wp-content\/themes -name \"*.php\" -print0 | xargs -0 -n1 php -l | grep -v \"^No syntax errors\"'<\/code><\/pre>\n
PHPStan: it finds it, but not at level 0<\/h2>\n
PHPStan analyses the code without running it, so it knows which functions and constants exist. On the ten-line example:<\/p>\n
--- level 0\nsrc\/more.php:5:Deprecated in PHP 8.0: Required parameter $b follows optional parameter $a.\nsrc\/more.php:5:Function each not found.\nsrc\/more.php:6:Function create_function not found.\n--- level 1\nsrc\/comments.php:7:Constant mytheme_comment not found.\n...<\/code><\/pre>\n
Look closely: in my run, level 0 did not report the undefined constant, level 1 did. If you introduce PHPStan to a legacy codebase at level 0 to keep the noise down, this class of bug still slips through. Start at level 1 at least.<\/p>\n
On the real WordPress theme, the first run is noise: every WordPress function is “not found”, because PHPStan does not know WordPress. The fix is the szepeviktor\/phpstan-wordpress<\/code> extension, which brings the WordPress stubs. With it, the old comments.php<\/code> at level 1 gives five lines, and every one of them is worth reading:<\/p>\n
theme\/comments.php:29:Function twentyfifteen_comment_nav not found.\ntheme\/comments.php:45:Constant mytheme_comment not found.\ntheme\/comments.php:93:Array has 2 duplicate keys with value 'label_submit' ('label_submit', 'label_submit').\ntheme\/comments.php:110:Variable $user_identity might not be defined.\ntheme\/comments.php:133:Array has 2 duplicate keys with value 'title_reply' ('title_reply', 'title_reply').<\/code><\/pre>\n
Line 45 is our fatal error. Line 29 is a function from the parent theme (Twenty Fifteen); tell PHPStan about the parent theme folder and it disappears. The duplicate keys and the possibly undefined variable are real sloppiness from 2015, the same family as the undefined $aria_req<\/code> I fixed in that file during the move. The configuration for that run is tiny:<\/p>\n
# phpstan.neon\nparameters:\n  level: 1\n  paths:\n    - public\/blog\/wp-content\/themes\/myblog<\/code><\/pre>\n
With phpstan\/extension-installer<\/code> the WordPress extension registers itself, no include needed. Higher levels find more PHP 8.1 problems: at level 5, strlen(null)<\/code> is reported as “Parameter #1 $string of function strlen expects string, null given”, which is exactly the PHP 8.1 deprecation for passing null to internal functions.<\/p>\n
PHPCompatibility: good for removed functions, blind to this bug<\/h2>\n
PHPCompatibility is a PHP_CodeSniffer standard that knows which functions and syntax changed between PHP versions. It does not know your code’s constants, so it did not report mytheme_comment<\/code> in either version, and on the real comments.php<\/code> it reported nothing.<\/p>\n
It also matters which version you install. The latest stable release, 9.3.5, is from before PHP 8 and told me only half the truth:<\/p>\n
# 9.3.5, testVersion 8.0-\nmore.php:5:38: warning - Function each() is deprecated since PHP 7.2; Use a foreach loop instead\n\n# 10.0.0-alpha2, testVersion 8.0-\nmore.php:5:17: warning - Declaring an optional parameter before a required parameter is deprecated since PHP 8.0. ...\nmore.php:5:38: error - Function each() is deprecated since PHP 7.2 and removed since PHP 8.0; Use a foreach loop or ArrayIterator instead<\/code><\/pre>\n
“Deprecated” versus “removed” is the difference between a log line and a white page. If you use PHPCompatibility for PHP 8 work, use the 10.x line (still alpha when I wrote this) and run it with --runtime-set testVersion 8.0-<\/code>.<\/p>\n
What I run now<\/h2>\n
    \n
  1. php -l<\/code> with the target PHP version over all files. Cheap, catches removed syntax.<\/li>\n
  2. PHPStan at level 1 or higher, with stubs for the framework (WordPress stubs, or the TYPO3 core in vendor\/<\/code> for extensions). Catches unknown constants, functions and classes.<\/li>\n
  3. PHPCompatibility 10.x for removed and deprecated functions and syntax across versions.<\/li>\n
  4. And then still: open every template type once on the target PHP version, with error logging on. On hoja.in the post pages with comments were the ones that died; a smoke test that only loaded the blog home would have passed.<\/li>\n<\/ol>\n
    The PHP 8 changes that bite legacy themes and extensions most<\/h2>\n