A plugin that needs newer PHP than you run

The symptom

The plugin activated without complaint and has been running for months. Its header says Requires PHP: 8.1. The server runs 8.0. Nothing on the store looks wrong.

This happens because the requirement is only enforced at the moment of installation through the WordPress admin. A plugin uploaded by FTP, restored from a backup, copied during a migration, or installed before the server was downgraded skips that check entirely — and once active, nothing re-checks it.

What it costs

Incompatible PHP does not fail gradually. It fails on the exact request that first reaches a line using syntax the interpreter does not know, and a parse error is fatal:

• The failure is white-screen, not degraded. PHP cannot partially parse a file. The page that loads that file returns a 500, and if it is loaded on every request, that is the whole store.
• It waits for a rare code path. The new syntax may sit in the refund handler, the tax calculation for one country, or the admin screen you open twice a year. It has not fired yet.
• It fires during updates. Plugin updates are exactly when new code lands, so the most likely moment for this to break is the moment you are already changing something else.
• The order matters. If the fatal is in a payment or checkout path, you find out from customers.

How to check it yourself

WP-CLI reads the plugin headers, and PHP reports its own version:

php -r 'echo PHP_VERSION, "\n";'
wp plugin list --status=active --fields=name,version --format=table

The requirement itself is in the header of each plugin’s main file:

grep -ri "Requires PHP" wp-content/plugins/*/*.php | grep -v "Requires PHP: *$"

Compare each result against the running version. WordPress also exposes this at Tools → Site Health, but only for plugins it installed itself.

How to fix it

1. Raise PHP rather than downgrade the plugin. Every currently supported PHP release is faster than the one before it, and a store on 8.0 is already past its own security window.
2. Test on a staging copy first, with every plugin active. The failures you are looking for are the ones that only appear on specific screens.
3. If a plugin cannot run on the newer version, that plugin — not the server — is the thing to replace. A plugin that cannot follow PHP is not being maintained.
4. Re-check after every migration. Moving a site to a new host is the most common way this mismatch is created.

When it is a false positive

• Plugins with a wrong or stale header. Some authors bump Requires PHP defensively, ahead of actually using newer syntax. The declaration is a promise about support, not always a technical requirement.
• Code paths that never run in your configuration — a plugin whose newer syntax lives only in an integration you have not enabled.
• Hosts that run different PHP versions for CLI and for the web server. Check the version the web server uses, not the one your shell reports.

How Merchlint finds it

Merchlint reads the Requires PHP header of every active plugin and of the active theme, and compares it against the PHP version serving the request — not the CLI version, which is frequently different. It reports each mismatch with both numbers and with whether the plugin is loaded on front-end requests or only in the admin, since that decides whether the risk is a broken storefront or a broken back office.

The same finding also lists plugins declaring no requirement at all, ranked lower — that is missing information rather than a mismatch.

Confidence: F — fact from the environment. One version number is lower than the other.

This check ships in the Pro add-on.