Web Design

PHP Compatibility Check for WordPress and Drupal: Test Plugins, Themes and Custom Code Before PHP 8.4

A low three-quarter photograph of a curved courtyard bench covered in glazed ceramic mosaic, a geometric pattern of small blue, ochre and white tiles, where a few new tiles near the center fill old gaps and two empty gaps remain beside a small stack of spare tiles, warm late-afternoon light, a visual for a php compatibility check of WordPress and Drupal plugins, themes and custom code

A PHP compatibility check tells you which plugins, themes, modules and custom code will break on PHP 8.3 or 8.4 before your host flips the switch. It takes three passes: a static scan of the code, a set of fixes, and a test run on staging with logging on. None of the three is enough alone.

Our PHP 8.2 end-of-life guide covers the deadline, each host’s own cutoff and how to pick a version. This post goes one level down: what plugin headers can tell you, how to scan and fix code, how Drupal fits in, and a reusable checklist.

The short version: plugin directory headers only tell you the minimum PHP a plugin needs, never the maximum it was tested on. Scan custom code with PHPCompatibility, which needs its 10.x pre-release to know about PHP 8.3 and 8.4. Fix the noisy deprecations with Rector, one rule at a time. Then run the site on staging and read the error log, because a scan cannot see everything.

PHP2Shell update: PHP2Shell, two critical PHP flaws that can allow unauthenticated remote code execution, was patched on October 21, 2026 in PHP 8.2.35, 8.3.36, 8.4.27 and 8.5.12. Sites on PHP 8.1 or older got no upstream release and depend on a host or vendor backport. See our PHP2Shell coverage for what to check.

Why plugin headers do not answer the PHP compatibility question

Each WordPress plugin directory page shows "Tested up to" and "PHP version" in its sidebar. Neither one answers the question.

"Tested up to" is a WordPress version, not a PHP version. The plugin readme documentation defines it as "The version of WordPress that the plugin has been tested against."

"Requires PHP" is a floor. The same page calls it "The required minimum version of PHP needed for use with this plugin." On the directory it shows as "PHP version: 7.2 or higher," or similar. Since WordPress 5.8, that header is read from the plugin’s main PHP file, not the readme.

WordPress does act on the floor. Since version 5.2, core blocks activation of a plugin that needs a newer PHP than the site runs, per Trac ticket 43992. No header states the newest PHP a plugin supports, so "7.2 or higher" says nothing about 8.4.

The changelog and "Last updated" date help more. A changelog that mentions PHP 8.3 or 8.4 fixes is a good sign. A plugin untouched for two years is a likely PHP compatibility problem.

The three passes of a PHP compatibility check

Each pass catches things the others miss.

Pass Tool What it finds What it misses
Scan PHPCompatibility for PHP_CodeSniffer Removed and deprecated functions, syntax and parameters, file by file Behavior changes at runtime, code paths built from strings, missing extensions on the server
Fix Rector Rewrites some patterns automatically, such as implicit nullable parameters Anything without a rule; it does not tell you what is broken
Run Staging site with debug logging What actually fails when real pages load and forms submit Code paths nobody clicks during the test

PHPCompatibility status as of October 2026

This section will date. Check the project pages before you install.

PHPCompatibility’s releases page showed these as of October 2026:

  • 9.3.5 is still marked “Latest,” the newest stable release. Its newest sniffs cover PHP 7.4. It knows nothing about PHP 8.3 or 8.4.
  • 10.0.0-alpha1 (October 2025) added sniffs grouped by version through PHP 8.4, including one for implicitly nullable parameters.
  • 10.0.0-alpha2 (November 28, 2025) added PHP 8.5 checks. It is marked as a pre-release.

The alpha1 notes say the work "is not yet complete, so some sniffs may still throw false positives/negatives." The README says coverage "is not yet 100%."

The WordPress ruleset follows the same pattern. PHPCompatibilityWP 2.1.8 is its latest stable release. Version 3.0.0, now at alpha2, is the one that requires PHPCompatibility 10. In practice, a PHP compatibility scan for 8.4 means running pre-release tools. That is fine on a development copy. Treat the output as a lead list.

How to run a PHP compatibility scan on a WordPress site

Run the scan on a local or development copy, never on the live server. Put the tools in their own folder outside the web root.

The PHPCompatibilityWP README gives these install commands:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcompatibility/phpcompatibility-wp:"^3.0@dev"

The ruleset "prevents false positives from the PHPCompatibility standard" by excluding functions that WordPress back-fills for older PHP versions. Use it for WordPress code. Use the plain PHPCompatibility standard for Drupal and other PHP.

Then point the scanner at one plugin or theme at a time, and tell it which PHP versions you care about:

vendor/bin/phpcs -p wp-content/plugins/example-plugin --standard=PHPCompatibilityWP --runtime-set testVersion 8.3-8.4

A testVersion range like 8.3-8.4 checks against both targets. Use 8.4 alone if that is the only version you will run.

Scan in this order: custom plugins and child themes first, then premium plugins, then free plugins from the directory. Your own code is the part nobody else will fix.

Reading PHP compatibility scan results

The report lists each file, line and message. Sort the findings into three groups.

Removed. The function, extension or syntax is gone on the target version. Code that uses it fails there, so these block the upgrade.

Deprecated. The code still runs, but PHP logs a notice. These are a to-do list, not a blocker. On PHP 8.4, implicitly nullable parameters will be the noisiest item by far.

Guarded code. Some findings sit inside a version check, such as function_exists() guarding a newer function. Read the code; if the guard holds, mark the finding and move on.

For a third-party plugin, do not patch the vendor’s code; the next update erases the patch. Update to its latest release and rescan. If findings remain, send them to the vendor or find a replacement.

Fixing PHP 8.4 deprecations with Rector

Rector rewrites PHP code by rule. Install it with composer require rector/rector --dev, and always preview with vendor/bin/rector process --dry-run before you apply anything.

Its PHP 8.4 rule set has eight rules. One matters most for a version upgrade: ExplicitNullableParamTypeRector, described as "Make implicit nullable param to explicit." It turns function foo(T1 $a = null) into the explicit nullable form that PHP 8.4 expects.

Be careful with the full set. Four of its rules rewrite loops to use array_find(), array_any(), array_all() and array_find_key(). PHP 8.4 added those functions, per the PHP 8.4 new functions list. Code rewritten that way stops running on 8.3. If a plugin must still run on 8.2 or 8.3, apply the single nullable rule, not the whole set.

Checking Drupal modules and custom code

On Drupal, Drupal Upgrade Status runs PHPStan and other checks to find what blocks the next Drupal major version. Its project page says it also "Checks if your system meets the next major version’s system requirements," and PHP is one of those requirements.

Upgrade Status is built for Drupal version upgrades. For a PHP 8.3 or 8.4 move, also run PHPCompatibility over your custom code:

vendor/bin/phpcs -p web/modules/custom web/themes/custom --standard=PHPCompatibility --runtime-set testVersion 8.3-8.4

For contributed modules, the rule is the same as WordPress plugins. Update to the newest release for your Drupal version, then test. Drupal 10.4 to 10.6 support PHP 8.1 through 8.4, so a Drupal 10 site can make this move now.

Drupal 10 reaches end of life on December 9, 2026. Upgrading PHP does not extend Drupal 10 support. See what Drupal 10 end of life means for your site and our plain-language Webform advisory guide for why unsupported add-ons matter.

Doing the PHP move first, on Drupal 10, keeps the Drupal 10 to 11 upgrade smaller. Drupal 11 needs PHP 8.3 or later anyway.

What a PHP compatibility check flags between 8.2 and 8.4

These are the items to expect, from the PHP migration guides. Sites on 8.2 already log the 8.2 notices.

Change Version Effect on old code
Dynamic properties deprecated 8.2 Notice when a class sets an undeclared property. Declare it, or add #[\AllowDynamicProperties]
range() and number_format() behavior changes 8.3 Different output with some inputs; rarely fatal
get_class() with no argument deprecated 8.3 Notice in older class code
Implicitly nullable parameters deprecated 8.4 Notice on every Type $x = null signature
IMAP, OCI8, PDO_OCI and PSpell moved to PECL 8.4 Fatal if the host does not install the extension
trigger_error() with E_USER_ERROR deprecated; E_STRICT constant deprecated 8.4 Notices in older error handling code

The PHP 8.4 deprecations page and the PHP 8.2 deprecations page have the full lists. The IMAP change also depends on the server. Code that calls it fails if the host has not installed the extension, so ask before you switch.

Looking further ahead, our post on what is shipping in PHP 8.6 covers the next round of deprecations.

Running the site on staging with logging on

The staging run is the final test. On WordPress, use the logging block from the WordPress debugging guide, which writes errors to a file without showing them on the page:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

The log goes to wp-content/debug.log by default. With WP_DEBUG on, the guide says WordPress shows "all PHP errors, notices, and warnings," including deprecation notices. Keep it on staging only.

Switch staging to the new version, click through every form and checkout path, then search the log. Lines with "Fatal error" block the upgrade. Lines with "Deprecated" go on the list. The file path in each line names the plugin responsible.

A step-by-step PHP compatibility checklist

  1. List every plugin, theme and module with its version. Note custom code separately.
  2. Check each third-party item’s changelog and last update date. Flag anything not updated in the past year.
  3. Copy production to a development or staging site. Update core and every add-on there first.
  4. Run PHPCompatibility with testVersion set to your target, custom code first.
  5. Sort findings into removed, deprecated and guarded code.
  6. Fix custom code. Use Rector’s single nullable rule for PHP 8.4 notices, and review each change.
  7. Send vendor findings to the vendor, or plan a replacement for abandoned plugins.
  8. Ask the host about extensions your code uses, IMAP above all, on the new version.
  9. Switch staging to the new PHP version with logging on and test every key path.
  10. Read the log, fix fatals, then switch production and keep watching the log for a few days.

Frequently Asked Questions

What is a PHP compatibility check?

A test of whether a site’s code will run on a newer PHP version: a static scan of the code plus a test run on a staging copy.

Does “Tested up to” on a WordPress plugin mean it works with PHP 8.4?

No. “Tested up to” is a WordPress version. The “PHP version” field shows only the minimum PHP the plugin needs.

Which PHPCompatibility version checks for PHP 8.3 and 8.4?

As of October 2026, only the 10.x pre-release. The stable 9.3.5 release has sniffs up to PHP 7.4. Check the project’s releases page for a stable 10.0.0 before you install.

Should I use PHPCompatibility or PHPCompatibilityWP for WordPress?

Use PHPCompatibilityWP. It is the same scanner with WordPress’s own back-filled functions excluded, so you get fewer false positives.

Can Rector fix everything the scan finds?

No. It has rules for some patterns, such as implicit nullable parameters. Removed extensions and behavior changes need a person.

Is it safe to run Rector’s full PHP 8.4 set?

Only if the code will never run on an older PHP version. Some rules rewrite code to use functions PHP 8.4 added, so the result fails on 8.3. For shared code, apply single rules.

Does Drupal Upgrade Status check PHP compatibility?

It checks the next Drupal major version’s requirements, including PHP. For PHP-version changes in custom modules and themes, run PHPCompatibility too.

Are deprecation notices a reason to delay the upgrade?

No. Deprecated code still runs. Fatal errors block the upgrade; deprecation notices are a list to work through over time.

Digital Matters

Web Design Desk