How to check if your WordPress plugins and themes will work on a newer PHP version
Before you or your host switches PHP, do four things. Make a backup. Update WordPress, your plugins and your theme. Scan the plugin and theme code against the PHP version you are moving to. Then try the new version on a copy of the site before the live one. The scan finds code that uses features the new PHP version deprecates or removes, and it tells you the file and line. No scanner catches everything, so the test on a copy is what tells you the site really works.
Why plugins and themes are the part to check
WordPress core publishes which PHP versions it supports. The core team's handbook keeps a table of WordPress releases against PHP versions and says the software is tested and compatible with the versions in that list. That covers WordPress itself, not the code you added to it. The same page gives the reason the newest PHP versions used to carry a "beta" label: WordPress is rarely used in isolation, without a theme or plugins.
So when a site breaks after a PHP upgrade, the cause is usually a plugin or theme that uses something the new PHP version deprecates or no longer allows. That is the code you need to check.
Start with what the plugin authors already tell you
Every plugin can declare a "Requires PHP" header. The WordPress plugin handbook describes it as the minimum required PHP version. That is useful, but read it correctly: it is a lower limit. It says the plugin needs at least that version. It does not say the plugin was tested on the newest one.
- Open each plugin's page on WordPress.org and look at its PHP requirement and when it was last updated. A plugin with no updates in a long time is the most likely to use old code.
- Read the changelog of your most important plugins for mentions of the PHP version you are moving to.
- Update everything first. Under its steps for before you update your PHP version, the WordPress.org guide says to update WordPress, themes and plugins, and when done, to check that your site is working as expected. Many PHP fixes ship as ordinary plugin updates.
Know what breaks between PHP versions
Each PHP release has a migration guide in the official manual with a list of deprecated features. Here are four of them, from PHP 8.2 and PHP 8.4:
| Change | What the old code looks like | Usual fix |
|---|---|---|
| Dynamic properties are deprecated (PHP 8.2) | A class sets $this->something without declaring it | Declare the property, or add the #[\AllowDynamicProperties] attribute to the class |
| ${var} string interpolation is deprecated (PHP 8.2) | "Hello ${name}" | "Hello {$name}" or "Hello $name" |
| utf8_encode() and utf8_decode() are deprecated (PHP 8.2) | utf8_encode( $text ) | Use mb_convert_encoding() instead |
| Implicitly nullable parameters are deprecated (PHP 8.4) | function get_label( WP_Post $post = null ) | function get_label( ?WP_Post $post = null ) |
Here is the nullable parameter change in code. The PHP manual explains that a parameter's type used to be quietly widened to accept null when its default value is null. That is now deprecated, and the fix is to say so in the type:
// Deprecated: the type silently accepts null
function get_label( WP_Post $post = null ) {}
// Fixed: the nullable type is written out
function get_label( ?WP_Post $post = null ) {}For dynamic properties, the PHP 8.2 migration guide lists three ways to address the warning: declare the property (preferred), add the #[\AllowDynamicProperties] attribute to the class, which also applies to all child classes, or use a WeakMap if additional data needs to be associated with an object you do not own. The same guide says stdClass allows dynamic properties.
Scan the code for these problems
Reading every file by hand is not realistic, so use a scanner. The standard rule set is PHPCompatibility, and its WordPress version is PHPCompatibilityWP: a ruleset for PHP_CodeSniffer that checks WordPress projects for PHP cross-version compatibility issues. It skips back-fills and polyfills that WordPress already provides, so you get fewer false alarms than with the plain rule set.
Its README says Composer is the only supported way to install it. If you work from a terminal, copy your site's wp-content folder to your computer and run this in a working folder:
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcompatibility/phpcompatibility-wp:"^3.0@dev"
vendor/bin/phpcs -i
# Scan plugins and themes for PHP 8.2 and newer
vendor/bin/phpcs -p path/to/wp-content/plugins path/to/wp-content/themes --standard=PHPCompatibilityWP --extensions=php --runtime-set testVersion 8.2-Always set testVersion. The README says that by default you will only receive notifications about deprecated and/or removed PHP features, and that setting a testVersion enables those checks as well as the detection of code using new PHP features. The --extensions=php option tells PHP_CodeSniffer to check only PHP files: the README notes that PHP_CodeSniffer before version 4.0 analyses PHP, JavaScript and CSS files by default, while the PHPCompatibility sniffs only target PHP code.
If you do not use a terminal, a plugin can run the scan from inside WordPress. The WordPress.org guide on updating PHP suggests the PHP Compatibility Checker plugin to check your themes and plugins for possible issues. It also says plainly that the plugin may miss items or flag false positives. That is true of every static checker, so treat a result as a list of things to look at, not a final verdict.
Another option is our free Bright Labs Compatibility Scanner for PHP (in beta). It reads every installed plugin and theme and lists each file and line that uses something removed or deprecated in the PHP version you pick, from PHP 8.2 to 8.5. It uses the current PHPCompatibility rules, not the 2019 release that some older checkers ship. It runs inside WordPress in short steps and needs no exec() or shell access, so it works on managed hosts that switch those off. The same limits apply: it reads code without running it, so a clean scan is a good sign, not a promise.
Test on a copy before switching the live site
A scanner reads code but does not run it. It can miss code that is built while the site runs, and it can flag code that never runs. The only way to know the site works is to run it on the new PHP version.
- Make a full backup first. The WordPress.org guide notes that a backup lets you put the site back to how it is right now if anything goes wrong.
- If your host offers a staging copy, switch PHP there first. Click through the pages that matter: checkout, forms, logins, search, and the admin screens you use every day.
- Watch for errors and deprecation notices in the PHP error log while you test. A notice is not a crash yet, but it marks the code that will cause trouble later.
- Only switch the live site once the copy works. If something does break on the live site, ask your host to restore the previous version of PHP you had running, then restore your backup if needed.
What to do when a plugin fails the check
Once the scan or the test names a plugin, work through these in order:
- Check for an update and scan again. The problem may already be fixed in a newer release.
- Contact the developer. The WordPress.org guide says to get in touch with the theme or plugin developer and ask them to investigate. Send the file and line the scanner reported, because that saves them time.
- Replace it. If the developer does not respond, the same guide suggests finding a plugin on WordPress.org with similar functionality and using that instead.
- Hold off on the upgrade if the plugin is essential and has no fix yet. Upgrade once the plugin is fixed, rather than running a site that is broken.
Do not edit a third-party plugin's files to silence a warning. The next update overwrites your change, and you may hide a problem instead of fixing it.
Sources
- WordPress Core Handbook: PHP Compatibility and WordPress Versions
- WordPress.org: Get the latest PHP version (updating PHP safely)
- WordPress Plugin Handbook: Header Requirements
- PHPCompatibilityWP ruleset on GitHub
- PHP Manual: Deprecated features when migrating to PHP 8.2
- PHP Manual: Deprecated features when migrating to PHP 8.4
Questions
Does a clean compatibility scan mean my site will work on the new PHP version?
No. Scanners read code without running it, so they can miss problems in code that is built at runtime and can flag code that never runs. The WordPress.org guide says its suggested checker may miss items or flag false positives. Treat a clean scan as a good sign and test on a copy of the site before you switch the live one.
Does the Requires PHP field on a plugin page mean it works on the newest PHP?
No. The plugin handbook defines it as the minimum required PHP version. It tells you the oldest version the plugin needs, not whether it was tested on the newest one.
Can I undo a PHP upgrade if my site breaks?
Yes. Ask your host to restore the previous version of PHP you had running, or switch it back yourself in your hosting panel if your host allows that. Restore your backup if the site still has problems.
Why does my site show deprecation notices but still work?
A deprecation means the PHP version you are on still runs that code but flags it. Common examples are dynamic properties and ${var} interpolation in PHP 8.2, and implicitly nullable parameters in PHP 8.4. Update the plugin or report the notice to its developer so the code is fixed before it causes real errors.