How to check PHP compatibility for a custom WordPress theme
Short answer
A custom theme, built for your site or by an agency, gets no updates: whatever breaks on a newer PHP version stays broken until someone changes it. Check it in two ways. Read the code for the PHP version you’re moving to: that finds removed functions and syntax, before you switch, in the theme, its child theme and its parent. Then run the pages on that PHP version on a staging copy, with a debug log: that finds what depends on data, and patterns a code check doesn’t cover. With both lists, the theme’s developer knows exactly what to change.
Why a custom theme needs its own check
A theme from wordpress.org or a theme shop gets updates; a custom theme only changes when someone edits it. And the theme runs on every page: if its functions.php stops on the new PHP version, the whole site shows a critical error.
Check every theme the site loads: the active theme, its parent if it’s a child theme (WordPress loads both, see child themes), and inactive themes you might switch to.
Check 1: read the code
Removed functions and old syntax are in the code, so a check that reads it finds them before you switch, with the file and line. A typical old-theme finding, a while … each() loop in functions.php that PHP 8.0 no longer runs:
CompatNav, a free plugin on wordpress.org, checks every installed theme along with the plugins, on your own server, for the PHP version you choose (8.0 to 8.5). In the report, the theme’s entry says whether the code looks like your own and has a before/after example for each finding, ready for the developer. The theme compatibility checker shows the screens.
Check 2: run the pages on the new version
Some problems only appear when the code runs, with your content and settings. And some old patterns stop a page on PHP 8 without being among the changes a code check looks for. An array key written without quotes in a template is one:
wp-content/themes/old-theme/header.php
<?php
$args = ['title' => 'Welcome'];
echo '<h1>', $args[title], "</h1>\n"; // the key has no quotes
<h1>
Warning: Use of undefined constant title - assumed 'title' (this will throw an Error in a future version of PHP) in /var/www/html/wp-content/themes/old-theme/header.php on line 3
Welcome</h1><h1>
Fatal error: Uncaught Error: Undefined constant "title" in /var/www/html/wp-content/themes/old-theme/header.php:3
Stack trace:
#0 {main}
thrown in /var/www/html/wp-content/themes/old-theme/header.php on line 3CompatNav’s scan of this example reports nothing, and PHP 7.4 printed the heading correctly; PHP 8.0 stops (why). To catch this kind:
- Make a staging copy of the site (how) and switch it to the new PHP version.
- Turn on the debug log there (how).
- Open every kind of page the theme renders: home, a post, a page, archives, search, 404, and any custom templates (shop, contact, landing pages).
- Read the log: each line names the theme file and line, such as “Undefined variable” or “count(): Argument #1 must be of type Countable|array”.
On PHP 7.4, the same log already shows many of these as warnings or notices. Searching it before you switch gives you a head start.
Then fix it
Give the developer both lists: the code findings (the downloadable report has a section for developers) and the log lines from staging. If nobody maintains the theme anymore, custom code and PHP 8 explains how to get exact changes to review. Before any edit, keep a copy of the theme, or better, put it under version control.
After the fixes, run both checks again, then switch the live site and watch its log for a week.
Key takeaways
- Custom themes get no updates, and the theme runs on every page: check it before any PHP upgrade.
- Check the child theme and its parent: WordPress loads both.
- Check 1, read the code: removed functions, old syntax, deprecations, with file and line.
- Check 2, run the pages on staging with a debug log: problems that depend on data, and patterns no code check reports.
- Fixes go to the theme’s developer; keep the theme in version control or at least keep a copy before editing.
Frequently asked questions
Is a child theme checked separately?
It should be, together with its parent: WordPress loads the child theme’s files and the parent’s. A check of installed themes covers both.
Can I edit a custom theme myself?
A custom theme gets no updates that would overwrite your changes, so editing it is possible. Keep a copy first, test on staging, and if a developer maintains it, go through them.
Which PHP version should I check for?
The one you’re moving to, ideally PHP 8.3 or newer: 8.3 gets security fixes until 31 December 2027, 8.4 until 31 December 2028, 8.5 until 31 December 2029.
Check your own site before you upgrade
CompatNav is a free WordPress plugin. It reads the code of your plugins and themes on your own server and tells you, in plain words, what will break and what will only show notices on the PHP version you choose. It never changes your code. It can’t see problems that only appear while code runs with real data, so a quick check of your site after the upgrade still matters.
Sources
About the code examples: each output is the real output of the code shown, run with the official PHP builds, without a php.ini, with all errors reported and displayed. Only the file path was replaced by a neutral server path.