Caching

What it does

Caching stores a finished copy of each page a site shows to visitors who are not logged in, and answers the next visitor from that copy before WordPress loads — no PHP theme rendering, no database queries. It runs on the client’s own server inside the WPClientHub One plugin; there is no CDN and nothing leaves the site. It is on every plan, Free included, and needs WPClientHub One 2.0 or newer on the site.

Three things come with it:

• Smart purge — a page is removed from the cache the moment its content changes, and everything is purged after the changes that touch every page (theme, plugins, menus, widgets, the Customizer, core) and after what WPClientHub itself does to a site: an update batch, a restore or rollback, a database cleanup, an image run.
• Preload — after a full purge the site warms its most important pages again in the background, a few at a time on its own cron, so visitors rarely meet a cold page.
• Static-file rules on Apache and LiteSpeed: browser caching (Expires / Cache-Control) for CSS, JavaScript, images and fonts, and gzip or Brotli compression for text, in a marked block of the site’s root .htaccess.

If the site already has a cache plugin — or the host caches pages itself — WPClientHub’s own cache stays off and says who handles it; purging from the dashboard still works through that plugin, and still happens on its own after updates, restores, cleanups and image runs. See Other cache plugins and hosts.

Where to find it

Open a site, pick the Performance tab: the Caching card sits under the report header. The Overview tab’s Performance card carries one line about it (“Cache on · 90% served from cache”). The card shows:

• The status — On, Switching on, Blocked on the site, Handled by plugin or host, Off, Plugin update needed, or Site not connected.
• Served from cache — the share of page views the cache answered over the last seven days (hits ÷ hits + misses), with the counts; pages cached and their size on disk; when pages expire; and what serves them (the PHP drop-in or the web server).
• Purge all and Purge URLs…, Settings, Check now (asks the site for its status), a preload in progress with a Stop button, the rules in effect, and the site’s last purges with their reasons.

Press Switch on caching (or turn it on in Settings) and the site installs its drop-in on the spot; Switching on means the settings are on their way and the site applies them on its next check-in.

What is cached, and what never is

Cached: whole HTML pages requested with GET (or HEAD) by a visitor who is not logged in, without a query string — tracking parameters are ignored by default (utm_*, gclid, fbclid, msclkid, dclid, mc_cid, mc_eid, _ga, _gl), so /pricing/?utm_source=newsletter gets the cached /pricing/. HTTP and HTTPS are cached apart. Pages are stored as a plain file and a gzip file under wp-content/cache/wpclienthub/ and expire after the time you set (10 hours by default).

Never cached, never answered from the cache:

• Anyone logged in, anyone who unlocked a password-protected post, a commenter with remembered details, a WooCommerce or Easy Digital Downloads session or cart, a password reset — by their cookies — and any cookie you add to the bypass list.
• The WooCommerce cart, checkout and account pages and the EDD checkout (found from the site’s own settings), and any path you exclude.
• Password-protected and private posts, previews, the Customizer, search results, feeds, embeds, robots.txt, the admin, the login page, the REST API, XML-RPC, cron, and anything under wp-content or wp-includes.
• POST requests, requests with an Authorization header or made by JavaScript (X-Requested-With), and any query string that is not on the ignore list.
• Redirects, 4xx and 5xx responses, responses that are not HTML, empty or truncated pages, pages over 5 MB, pages that start a session, pages sent with Cache-Control: no-store or private, and any page where a plugin defined DONOTCACHEPAGE — the constant every WordPress cache plugin honours.

Phones and desktops get the same copy unless you switch on separate copies for phones — most responsive themes serve one HTML to both, so it is off by default.

How a cached page is answered

The PHP drop-in (default, everywhere). Switching caching on writes wp-content/advanced-cache.php — the drop-in WordPress itself loads very early, before plugins, the theme or a database connection — and adds define( 'WP_CACHE', true ); to wp-config.php when it is not already there. The drop-in looks for the page’s file and, when it exists and is fresh, sends it and stops; otherwise WordPress loads exactly as it would without it. It fails open: if the WPClientHub One plugin folder or the cache configuration is missing (the plugin was deleted by hand, say), it does nothing and the site works normally. The hit is marked with an X-WPCH-Cache: HIT header; a page WordPress rendered carries MISS.

The web server (Apache and LiteSpeed, optional). Pick Web server in Settings and the plugin adds rewrite rules to the site’s root .htaccess — before WordPress’s own block — that answer a cached page without starting PHP at all: a GET with no query string, no login, session or bypass cookie and no Authorization header, on a path that is not excluded, when the file exists. The plugin then checks itself: it stores a probe page, requests it from the site, and looks for the probe and the X-WPCH-Cache: HIT (server) header. If the check fails (mod_rewrite off, AllowOverride None, a proxy in front) the page rules come out again and the PHP drop-in keeps serving; the card says why. The browser-caching and compression rules stay either way. The web-server path needs HTTPS and is not used with separate phone copies (the server cannot tell phones apart).

nginx. nginx does not read .htaccess, so the PHP drop-in serves pages. The card offers a snippet for the server block that does three things: compression and browser caching for static files, and a try_files that answers cached pages straight from the cache folder, with the same cookie and query-string rules. Paste it, reload nginx, and the drop-in simply has nothing left to do.

Purging

On the site, as content changes (one purge per request, at the end of it):

A purge of everything is one rename of the pages folder, so it takes the same instant whether the site has 50 pages or 20,000; the old files are deleted by the hourly garbage collection. A page that was still rendering when the purge happened is never stored afterwards — the request’s start time is compared with the purge stamp — so a slow request cannot put a stale page back.

From WPClientHub:

• Purge all and Purge URLs… on the card (owners, admins and techs). Everything, or up to 50 addresses at a time — addresses that are not the site’s are ignored and listed back. Done in the request, through the site, with the result in the Activity Log.
• After an update batch (manual or AutoPilot), a restore or rollback, a database cleanup and an image run, on its own. The site also purges itself the moment WPClientHub’s updates are installed and the moment a restore finishes, so AutoPilot’s after-screenshots never see a stale page; the purge WPClientHub sends afterwards then comes back “already purged a moment ago” and is logged as that. A full purge within a minute of the last one is reported rather than repeated, so nothing restarts the preload twice.
• On a site linked to Cloudflare (Scale) with auto-purge on, the same events purge the zone too — one fan-out, so no page is fresh on the site and stale at the edge.
• Through the public API on Scale: POST /api/v1/sites/{site}/cache/purge. See the API.

Every purge from WPClientHub is one line in the Activity Log (cache.purged, with the reason and what was purged — the WPClientHub cache, the other plugin, or “by the site itself”), and the site keeps its own log of the last twenty purges with their reasons, shown on the card.

Preload

After every full purge (and from the card on demand) the site warms its cache again: the front page, the posts page, then the newest 500 published posts and pages, newest first — the set its XML sitemap lists. It requests them from itself with a header the cache recognises, a few pages per WP-Cron tick inside a time budget, never inside a visitor’s request, and skips pages that are already fresh. Pages visitors open meanwhile are cached as they go. If the site cannot reach itself (a host that blocks loopback requests) the preload stops after a few failures and the card says so — the cache still fills as visitors browse. Switch it off in Settings for a site that should not spend its cron on it.

Settings

Per site, from the card’s Settings button. Saving sends the settings to the site as one signed instruction (the same way the white-label and image settings travel); the card says Applied once the site has confirmed them, or Pending until its next sync. Anything that changes what a stored page looks like — phone copies, cookies, query parameters, exclusions, minify, defer — empties the cache on the site first.

Other cache plugins and hosts

Two page caches on top of each other only make purging harder, so when one of these is active WPClientHub’s own cache stays off (its drop-in, WP_CACHE line and .htaccess block are not installed, or are removed) and the card says Handled by …. Purging from the dashboard, the automatic purges and the API still work through that plugin’s or host’s own purge function, where it has one:

Plugins are recognised by their plugin file, hosts by the constants and environment they set. A purge function that is missing or that throws is reported on the card and in the Activity Log, never a fatal error on the site. Deactivate the other plugin and WPClientHub’s cache takes over on the site’s next check-in, if it is switched on.

In client reports

A site whose cache has counted page views gets one line in the Performance section of its client report: “Cache: 90.4% of page views were served from the cache this week (13,730 page views, 184 pages cached).” Sites without data — the cache off, or handled by another plugin — get no line.

On the public API

On Scale, GET /api/v1/sites/{site}/cache (scope sites:read) returns the state, who handles it, the expiry, how pages are served, cached pages and bytes, hits and misses over seven days with the ratio, and the last purge. POST /api/v1/sites/{site}/cache/purge (scope sites:write) purges everything, or the urls you send — done in the request, through the site, logged with the key’s name. See the API reference.

Limits and honest notes

• Multisite networks are not supported yet; the card says so and nothing is installed.
• Plain permalinks (?p=123) cannot be cached — every page would be a query string. The card warns; switch the site to pretty permalinks.
• The hit ratio counts page views the cache saw: hits answered by the drop-in or (on nginx, with the snippet) not counted at all, and misses WordPress rendered. Bots count like anyone else. It is a measure of the cache, not analytics.
• A page a plugin builds per visitor without a cookie or DONOTCACHEPAGE (a geolocation banner, a random testimonial) is cached like any other page. Exclude its path.
• The drop-in reads a small config file on every uncached request; on a site with caching off it is not there and nothing runs. The hourly garbage collection and the preload use the site’s WP-Cron — a site whose cron never runs (DISABLE_WP_CRON without a system cron) keeps expired files a little longer and does not preload.
• No object cache, no fragment cache, no CDN. The Cloudflare integration on Scale covers the edge; this covers the origin.

Troubleshooting