Requires PHP: What to Declare and Why It Matters

"Requires PHP" is the plugin header that tells WordPress the minimum PHP version your code needs to run. Get the number wrong — too low and you ship fatal errors to users on ancient hosting; too high and you lock out a chunk of your install base for no real benefit. Most developers copy whatever number was in the boilerplate they started from and never revisit it. That's the mistake.

What the Requires PHP Header Actually Does

When a user tries to install or activate your plugin, WordPress checks the declared Requires PHP value against the server's actual PHP version. If the server is below that version, WordPress blocks activation and shows a message explaining why — before your code ever executes.

That's the entire point of the header: it converts a potential fatal error (white screen, broken site, confused support ticket) into a clean, pre-flight refusal with an explanation. Without it, PHP just chokes on a syntax feature or function it doesn't recognize and the user is left debugging a crash with no context.

Where to Declare It

You declare the same value in two places, and both matter for different reasons.

1. The plugin's main PHP file header

This is what WordPress core actually reads to enforce the version check at activation time:

• Requires PHP: 7.4 — add this line inside the standard plugin header comment block, alongside Plugin Name, Version, and Requires at Least.

2. The readme.txt header

The WordPress.org plugin directory parses this line to populate the "Requires PHP" field shown on your plugin page, and it's what the directory's compatibility filter uses when users browse WordPress plugin rankings by requirement.

• Same syntax: Requires PHP: 7.4 in the top metadata block of readme.txt, above the short description.

If these two numbers drift apart — a common bug after a dependency bump — the directory shows one version while core enforces another. Keep them in sync on every release.

Requires PHP vs. Requires at Least: Not the Same Header

Developers confuse these constantly because they sit next to each other in the same header block.

If you're auditing one, audit the other — our dev's playbook on supporting the current WordPress version covers the Tested up to and Requires at Least side of this same decision.

What Number Should You Actually Declare?

Pick the lowest PHP version your code genuinely runs on without errors — not the lowest version theoretically still receiving a security patch somewhere, and not just whatever your local Docker image happens to run.

WordPress core itself still lists 7.2.24 as its bare technical minimum but recommends 7.4+ on its own requirements page — core is far more conservative than the PHP project's own EOL schedule, because core has to support ancient shared hosting that plugins don't need to.

A practical rule: set Requires PHP to the lowest version that passes your actual test suite, not the lowest version you assume works. If you've never tested on 7.4, don't claim 7.4.

Why This Trips Developers Up

• Boilerplate inertia. Most scaffolding tools default to a number set years ago and nobody bumps it on releases.
• Fear of losing installs. Raising the floor from 7.4 to 8.0 feels like it will tank install numbers, but in practice it mostly blocks users who were already heading for a support ticket.
• Composer dependencies silently raise the real floor. You add a library that requires PHP 8.1 internally, your plugin's declared header still says 7.4, and activation succeeds right up until that code path runs.
• No monitoring. Nobody tracks what PHP versions their actual install base is running, so the number in the header is a guess instead of a measurement.

Before you change the number either direction, look at what comparable plugins in your category declare. Run a few through the plugin & theme detector or pull a side-by-side with competitor analysis — big plugins like WooCommerce and Elementor publish their current floors in readme.txt, and their support forums are a good proxy for what breaks when a version bump goes out.

What Happens If You Get It Wrong

Set too low

• Plugin activates on PHP it can't actually run on.
• Fatal error, white screen, or a silently broken feature — the user blames your plugin, not their host.
• One-star reviews citing "broke my site" that never mention PHP, because the user has no idea what PHP is.

Set too high

• Clean activation block with a readable message — much better than a crash.
• But you lose installs from users on older shared hosting who won't bother asking their host to upgrade.
• Directory search and filters on WordPress.org can also surface your plugin differently depending on the declared requirement, which affects discovery alongside the usual factors that drive plugin page conversions.

The too-high failure mode is annoying. The too-low failure mode generates support tickets, refund requests, and reviews that tank your average rating. Given the choice, err slightly conservative.

A Simple Process for Picking and Maintaining the Number

1. Check your actual Composer/npm dependency tree for the highest PHP floor any library requires — that's your real minimum, not an assumption.
2. Run your test suite against that version plus one version below it to confirm the boundary.
3. Set Requires PHP to match in both the plugin header and readme.txt.
4. Re-check it on every major release, especially after adding a new dependency.
5. Watch your support forum for PHP-version-shaped bug reports (fatal errors mentioning functions that don't exist) as a signal your declared floor is wrong.

If you're also researching what else affects how your plugin gets found and installed, our keyword research tool and the breakdown on plugin keyword cannibalisation cover the discovery side; this header covers the "does it even activate" side.

The Bottom Line

Requires PHP is cheap insurance. It costs one line in two files and it converts crashes into clear messages. Measure your real dependency floor, declare it honestly, and revisit it every release instead of letting it fossilize at whatever number a scaffold generated three years ago.