PHP upgrade checklist for WordPress agencies (client sites)

1. Inventory: one row per site

For every client site, record from Tools → Site Health → Info → Server: the exact PHP version and the PHP SAPI. Add the host, any deadline the host announced, and who to contact. A hosting panel often shows only the series (8.3), not the patch (8.3.36) (why that matters). How to set up the table: checking PHP compatibility across many client sites.

2. Triage into three lists

List	Which sites	Action
Patch now	8.2 to 8.5, below 8.2.35, 8.3.36, 8.4.27 or 8.5.12	Host updates PHP; no compatibility check needed
Upgrade now	PHP 7.4, 8.0, 8.1	Check, then upgrade to 8.3 or 8.4
Upgrade before January	PHP 8.2 (patched)	Check, then upgrade before 31 December 2026

Source for the versions: php.net. Within each list, start with sites that have logins, shops and forms, and with those whose PHP SAPI is apache2handler (mod_php), the setup php.net considers most at risk (why).

3. Hosts

Send each host the questions in what to ask your host: when they update, whether they apply backports for old versions, and which versions you can switch to. Keep their answers with the site’s row.

4. Clients

For upgrades, tell the client before you act: what, why, when, and what you need from them. Telling a client about a PHP upgrade has a message you can adapt.

5. Check, upgrade, report

Check each site’s plugins and theme for the target version, and fix what will break (what to do).
Upgrade at a quiet time, on staging first where possible (how).
Watch the error log for a week (how).
Send a short report: old and new version, what was fixed, what’s left (a maintenance report).

Per client site

Exact PHP version and SAPI recorded (Site Health)
Put in a list: patch now, upgrade now, or upgrade before January
Host asked, answer recorded
Client informed, date agreed
Plugins and theme checked for the target version
Everything marked “Will break” fixed
Upgraded; new version confirmed in Site Health
Log watched for a week; report sent

To keep it on paper, print this page: the website’s menus are left out.

The free CompatNav plugin does step 5.1 on each site, on that site’s own server. For many sites, the box below shows what CompatNav Pro adds.

Key takeaways

Record each site’s exact PHP version from Site Health, not the series from a hosting panel.
Three lists: patch now (hosts), upgrade now (7.4–8.1), upgrade before January (8.2).
Check each site’s plugins and theme for the target version before any upgrade.
Tell clients in plain words, with a date and what you need from them.
After the upgrade, keep the log for a week and send a short report.

Frequently asked questions

Do clients need to approve a PHP security patch?

A patch in the same series (8.3.35 to 8.3.36) changes no features, so it usually fits under maintenance; follow what your contract says. A version change (8.1 to 8.3) changes how the site runs, so inform the client and agree on a date.

How do I prioritise dozens of sites?

Unpatched and unsupported first, then by risk: sites with logins, shops and forms, and sites on hosts that use Apache with mod_php, which php.net considers most at risk.

What if a client’s host doesn’t update?

Ask in writing with the advisory link; if they can’t, plan a move to a host that does. Document it for the client.

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.

Get CompatNav on wordpress.org How it works

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.