PHP compatibility checker for WordPress plugins: what a good one checks
Short answer
A useful PHP compatibility checker for WordPress does six things: it checks every plugin and theme for the PHP version you are moving to, reports only what changes between your version and that one, separates what will break from what only adds notices, ignores code that is already protected, runs on your own server, and is honest about what it can’t see. The free CompatNav plugin was built around exactly these points, for PHP 8.0 to 8.5.
The problem
Your host announces a PHP upgrade, or you want to leave a version that’s running out of security fixes: PHP 8.2 gets them until 31 December 2026 (php.net). You need to know which of your plugins will survive. A compatibility checker should answer that before the switch, not after.
Six things a good checker does
1. It checks every plugin and theme
Including the inactive ones (they only matter if someone activates them) and the theme, which runs on every page. Custom code that nobody else maintains matters most: no update will ever fix it for you.
2. It checks for your target version
“PHP 8 compatible” means little: PHP 8.0 and 8.5 are five years apart, and each version has its own changes. You need an answer for the version you are moving to.
3. It reports only what changes for you
Moving from 8.2 to 8.4 has nothing to do with what changed in PHP 7.0. A check that lists every problem since PHP 5 buries the few that matter for your move.
4. It separates what breaks from what only warns
A fatal error stops the page; a deprecation notice only writes a line in the log (what each level means). A list that mixes both makes everything look urgent.
5. It skips code that is already safe
Many plugins already protect new code with function_exists() or a PHP version check. Reporting those lines anyway is a false alarm, and false alarms teach people to ignore the tool.
6. It runs on your server, and admits its limits
Your plugins’ code stays on your server, and the checker tells you which files it couldn’t read and what no code check can see. Online checkers versus on-server checks goes into the privacy side.
How CompatNav does it
CompatNav is a free plugin on wordpress.org built around these six points:
- Every plugin and theme, PHP 8.0 to 8.5: 58 checks for the changes each version brings; you choose the version you plan to move to.
- Only what changes between the PHP version the site runs today and the one you choose.
- One verdict: “Safe to upgrade”, or “Not ready yet” with a short list of what to do first, and each finding labelled “Will break” or “Deprecation notice”.
- Protected code is not reported: code already guarded by a PHP version check or
function_exists(). - On your server, read-only: no code, file names or results are sent anywhere; it never runs or changes the code it checks.
- Honest limits: files it couldn’t check are listed with the reason, and while any active file couldn’t be checked, the verdict never says “Safe to upgrade”.
On a test site with 17 plugins and themes (8,374 PHP files), a full scan took about 70 seconds. On three of the most-installed plugins together (about 7,800 PHP files), it reported 27 items for an upgrade from PHP 7.4 to 8.5, all deprecation notices, each checked by hand.
What a finding looks like
Each finding names the plugin, the file and line, explains the problem in plain words, and has a line for the developer. A real one, from code that a newer PHP refuses to load:
Getting started shows the first scan step by step.
Key takeaways
- Check every plugin and theme, for the PHP version you’re actually moving to, not a generic “PHP 8”.
- Only what changes between your version and the target matters; old warnings about versions you’ve already passed are noise.
- Separate “will break” from “deprecation notice”: only the first stops a page.
- Code protected by a version check or
function_exists()shouldn’t be reported. - The check should run on your server, and tell you which files it couldn’t check.
Frequently asked questions
Is there a free PHP compatibility checker for WordPress?
Yes. CompatNav is free on wordpress.org: it checks every plugin and theme for PHP 8.0 to 8.5 with 58 checks, on your own server, and gives one verdict in plain words.
Can a checker find every PHP problem?
No checker that reads code can. Problems that depend on values while the site runs, such as passing null to a PHP function, only show up in the error log. A good checker says so, and lists the files it couldn’t check.
Does checking change my plugins?
It shouldn’t. CompatNav only reads files: it never runs or changes the code it checks.
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.