← All changes | includes/class-cache.php +9713 -223 1.0.6 → 1.4.2 View file →

		@@ -11,8 +11,64 @@
11	11
12	12	class Cache {
13	13
14	14	/**
	15	+ * Response header the generated server rules stamp themselves with, so a
	16	+ * cache hit says which version of the rules served it. See
	17	+ * rules_marker_expected() for what the value means.
	18	+ */
	19	+ public const RULES_HEADER = 'X-XSpeed-Rules';
	20	+
	21	+ /**
	22	+ * Response header carrying the unix time the served HTML was generated.
	23	+ *
	24	+ * Free owns it on every path where PHP runs, and emits it from the same
	25	+ * `filemtime()` of the file it is about to send: the drop-in stamps it in
	26	+ * advanced-cache.php, and the template_redirect serve path stamps it in
	27	+ * serve_not_modified(). The nginx and Apache static paths never emit it —
	28	+ * no PHP runs there, so a consumer reads their `Last-Modified` instead.
	29	+ *
	30	+ * An add-on cannot supply this value, and edge_headers_for() strips it
	31	+ * from the `xspeed_edge_cache_headers` result in every context rather
	32	+ * than asking add-ons not to try. Nothing on the filter's side of the
	33	+ * seam knows which file is being served: mark() resolves the filter with
	34	+ * no file and no mtime, so an add-on has only time(), which is when the
	35	+ * page was SERVED. A downstream purge verifier compares this stamp with
	36	+ * the moment it asked for the purge, and a stamp that is always "now"
	37	+ * makes every purge look like it worked — worse than sending nothing.
	38	+ */
	39	+ public const BUILT_HEADER = 'X-XSpeed-Built';
	40	+
	41	+ /**
	42	+ * The headers that can grant an edge a lifetime: `Cache-Control`,
	43	+ * `CDN-Cache-Control`, `Cloudflare-CDN-Cache-Control`,
	44	+ * `Surrogate-Control`, `Edge-Control`. Matched on the header NAME.
	45	+ *
	46	+ * advanced-cache.php carries a copy of this and of the pattern below,
	47	+ * because the class is not loaded when the drop-in runs. Change all four
	48	+ * together; EdgeLifetimeEntryCapTest compares them.
	49	+ */
	50	+ public const EDGE_LIFETIME_HEADER = '/(?:^|-)control$/i';
	51	+
	52	+ /**
	53	+ * A lifetime directive inside one of those headers, and its seconds.
	54	+ * See cap_edge_lifetime().
	55	+ */
	56	+ public const EDGE_LIFETIME_DIRECTIVE = '/(?<![\w-])(max-age|s-maxage)\s*=\s*"?(\d+)"?/i';
	57	+
	58	+ /** Map of rules hash => the settings fingerprint that produced it. */
	59	+ public const RULES_INPUTS_OPTION = 'xspeed_rules_inputs';
	60	+
	61	+ /**
	62	+ * User meta holding {hash, at}: the rules version this admin says they
	63	+ * pasted into the server config. See rules_copied().
	64	+ */
	65	+ public const RULES_COPIED_META = 'xspeed_nginx_rules_copied';
	66	+
	67	+ /** How many rules versions the map above remembers. */
	68	+ private const RULES_INPUTS_KEPT = 10;
	69	+
	70	+ /**
15	71	* Output-buffer nesting level at which we opened our cache buffer, so
16	72	* `close_buffer()` can flush ONLY our buffer and never disturb a buffer
17	73	* another plugin pushed on top of (or below) ours.
18	74	*
		@@ -19,11 +75,181 @@
19	75	* @var int|null
20	76	*/
21	77	private static $buffer_level = null;
22	78
	79	+ /**
	80	+ * Bytes freed by the current sweep, accumulated by sweep_delete().
	81	+ *
	82	+ * A counter rather than a return value because the two sweeps that free
	83	+ * the bytes — the flat glob loop and the recursive static walk — already
	84	+ * report a FILE count, and `wp xspeed purge` needs both numbers from a
	85	+ * single pass. Re-walking the tree to size it would double the I/O on
	86	+ * exactly the caches large enough for the number to matter.
	87	+ *
	88	+ * @var int
	89	+ */
	90	+ private static $sweep_bytes = 0;
	91	+
	92	+ /**
	93	+ * The `X-XSpeed-Cache` value decided for this request, and — when the
	94	+ * decision was BYPASS — the slug of the gate that made it.
	95	+ *
	96	+ * Recorded as well as sent so unit tests (CLI SAPI, where header() is a
	97	+ * no-op and headers_sent() is meaningless) can assert on the decision.
	98	+ *
	99	+ * @var string
	100	+ */
	101	+ private static $status_header = '';
	102	+ private static $bypass_reason = '';
	103	+
	104	+ /**
	105	+ * Edge/CDN headers decided for this request, after sanitising.
	106	+ *
	107	+ * Same reason as $status_header: header() cannot be observed from the CLI
	108	+ * SAPI, so the pairs we sent are recorded here too.
	109	+ *
	110	+ * @var array<string,string>
	111	+ */
	112	+ private static $edge_headers = array();
	113	+
	114	+ /**
	115	+ * This entry's edge headers when they differ from the site-wide bake,
	116	+ * resolved once per store. Null until asked.
	117	+ *
	118	+ * @var array<string,string>|null
	119	+ */
	120	+ private static $per_entry_edge = null;
	121	+
	122	+ /**
	123	+ * Cache key whose write was deferred to shutdown because a render-time
	124	+ * translation plugin's buffer wraps ours. Null on every ordinary request.
	125	+ *
	126	+ * @var string|null
	127	+ */
	128	+ private static $deferred_key = null;
	129	+
	130	+ /**
	131	+ * Translated page HTML captured by the outer buffer, for the deferred
	132	+ * write. Only populated when a translation plugin is active.
	133	+ *
	134	+ * @var string
	135	+ */
	136	+ private static $translated_output = '';
	137	+
	138	+ /**
	139	+ * Did finalize_buffer() run to completion on this request?
	140	+ *
	141	+ * The deferred translated write runs as a PHP shutdown function, which
	142	+ * fires after a `wp_die()` or a bare `exit()` exactly as it does after a
	143	+ * clean render. Only finalize_buffer() sets this, and only at the point
	144	+ * where it has the full buffer in hand — so an aborted render leaves it
	145	+ * false and the writer declines rather than caching a truncated page
	146	+ * under the real key.
	147	+ *
	148	+ * @var bool
	149	+ */
	150	+ private static $render_completed = false;
	151	+
	152	+ /**
	153	+ * Minifier::purge_stamp() when this request's cache buffer opened.
	154	+ *
	155	+ * A render names its minified and combined files while it runs and is
	156	+ * stored when it ends. A purge that deletes those files in between would
	157	+ * otherwise leave a stored page linking files that are gone, for the
	158	+ * whole TTL. The stamp changes whenever such a purge deletes anything, so
	159	+ * a different value at store time means "do not store this one".
	160	+ *
	161	+ * Null when maybe_start_cache() opened no buffer. A direct call (tests,
	162	+ * add-ons) has nothing to compare against and stores as before.
	163	+ *
	164	+ * @var string|null
	165	+ */
	166	+ private static $asset_stamp_at_open = null;
	167	+
	168	+ /**
	169	+ * The snapshot above, carried to the deferred (translated) writer.
	170	+ *
	171	+ * @var string|null
	172	+ */
	173	+ private static $deferred_asset_stamp = null;
	174	+
	175	+ /**
	176	+ * Hooks that get an argument-aware handler instead of a blanket purge.
	177	+ *
	178	+ * Each fires on an ordinary visitor action — an order, a review, a
	179	+ * registration — where purge_all() cannot see WHAT changed and so wiped
	180	+ * the whole cache on every one. They are re-bound further down to
	181	+ * handlers that inspect the payload first.
	182	+ *
	183	+ * Listed here so the generic invalidation loop skips them. It binds a
	184	+ * closure (to name the cause), and a closure cannot be unbound by the
	185	+ * remove_action() pairs below — binding one would leave the coarse purge
	186	+ * running alongside its replacement and silently undo #243.
	187	+ */
	188	+ private const TARGETED_INVALIDATION_HOOKS = array(
	189	+ 'save_post',
	190	+ 'before_delete_post',
	191	+ 'trashed_post',
	192	+ 'comment_post',
	193	+ 'wp_set_comment_status',
	194	+ 'user_register',
	195	+ 'profile_update',
	196	+ );
	197	+
23	198	public function __construct() {
24		- add_action( 'template_redirect', array( $this, 'maybe_start_cache' ), 0 );
	199	+ /**
	200	+ * When the page-cache output buffer opens.
	201	+ *
	202	+ * Filterable because buffer ORDER decides what gets cached. PHP's
	203	+ * output buffers are LIFO: the last one opened is innermost, and its
	204	+ * callback runs first. A render-time translation plugin that opens
	205	+ * an outer buffer therefore translates AFTER we have already captured
	206	+ * and cached the raw HTML — see translation_buffer_compat().
	207	+ *
	208	+ * @param string $hook Hook to open the buffer on.
	209	+ * @param int $priority Priority for that hook.
	210	+ */
	211	+ $hook = (string) apply_filters( 'xspeed_cache_buffer_hook', 'template_redirect' );
	212	+ $priority = (int) apply_filters( 'xspeed_cache_buffer_priority', 0 );
	213	+ add_action( $hook, array( $this, 'maybe_start_cache' ), $priority );
25	214
	215	+ // When a render-time translation plugin is present, open one extra
	216	+ // buffer OUTSIDE its own so we can capture post-translation HTML.
	217	+ // TranslatePress opens on `init` priority 0, so we take a negative
	218	+ // priority to land outside it. This buffer only collects bytes for
	219	+ // the deferred cache write — it never modifies the response.
	220	+ add_action(
	221	+ 'init',
	222	+ static function () {
	223	+ if ( ! self::translation_plugin_active() ) {
	224	+ return;
	225	+ }
	226	+ // `init` fires on EVERY request type, and
	227	+ // translation_plugin_active() is a class_exists() check that
	228	+ // is true site-wide — so without this guard the buffer opened
	229	+ // on REST, admin-ajax, cron and WP-CLI too. None of those
	230	+ // reach template_redirect, so $deferred_key stays null and
	231	+ // the collected bytes are never released: a long-running
	232	+ // WP-CLI command copied every byte of its output into a
	233	+ // string that grew for the life of the process.
	234	+ if ( is_admin()
	235	+ || wp_doing_ajax()
	236	+ || wp_doing_cron()
	237	+ || ( defined( 'REST_REQUEST' ) && REST_REQUEST )
	238	+ || ( defined( 'WP_CLI' ) && WP_CLI )
	239	+ || ( defined( 'XMLRPC_REQUEST' ) && XMLRPC_REQUEST ) ) {
	240	+ return;
	241	+ }
	242	+ ob_start(
	243	+ static function ( $chunk ) {
	244	+ self::$translated_output .= $chunk;
	245	+ return $chunk;
	246	+ }
	247	+ );
	248	+ },
	249	+ (int) apply_filters( 'xspeed_translation_outer_buffer_priority', -100 )
	250	+ );
	251	+
26	252	// Events that should invalidate cached output. Beyond posts/comments,
27	253	// this covers user and term changes — the REST cache can serve
28	254	// /wp/v2/users, /wp/v2/categories, /wp/v2/tags, and these also affect
29	255	// rendered author bylines / term-archive pages. Without them, an edit
		@@ -29,9 +255,9 @@
29	255	// rendered author bylines / term-archive pages. Without them, an edit
30	256	// left the matching endpoint (and archives) stale for the full TTL.
31	257	// (FBS-82408)
32	258	$invalidate_hooks = array(
33		- 'save_post', 'deleted_post', 'trashed_post',
	259	+ 'save_post', 'before_delete_post', 'trashed_post',
34	260	'comment_post', 'wp_set_comment_status',
35	261	'switch_theme', 'activated_plugin', 'deactivated_plugin',
36	262	// Users → /wp/v2/users + author archives.
37	263	'profile_update', 'user_register', 'deleted_user',
		@@ -36,16 +262,229 @@
36	262	// Users → /wp/v2/users + author archives.
37	263	'profile_update', 'user_register', 'deleted_user',
38	264	// Terms → /wp/v2/{taxonomy} + term archives.
39	265	'created_term', 'edited_term', 'delete_term',
	266	+ // Menu structure changes (reorder, rename, assign to a location)
	267	+ // fire only here — the per-item `nav_menu_item` save_post does
	268	+ // not cover them. (#270 regression)
	269	+ 'wp_update_nav_menu',
40	270	);
41	271	foreach ( $invalidate_hooks as $hook ) {
42		- add_action( $hook, array( __CLASS__, 'purge_all' ) );
43		- add_action( $hook, array( 'XSpeed\\Minifier', 'purge_minified' ) );
	272	+ // Name the hook in the cause rather than binding purge_all bare.
	273	+ // Bound bare, WordPress passes the action's own first argument
	274	+ // into $cause — a term id, a user id, a menu id — so the activity
	275	+ // feed read "Cache purged (12)" and told the user nothing about
	276	+ // what happened. (#270 QA round 2)
	277	+ //
	278	+ // The four hooks that get an argument-aware handler below
	279	+ // (save_post, comment_post, user_register, profile_update) are
	280	+ // deliberately NOT wired here: a closure cannot be unbound by
	281	+ // remove_action(), so binding one would leave the coarse purge in
	282	+ // place alongside its replacement and silently undo #243. Skipping
	283	+ // them is equivalent — each is re-added with its own handler, and
	284	+ // each of those names its own cause.
	285	+ if ( in_array( $hook, self::TARGETED_INVALIDATION_HOOKS, true ) ) {
	286	+ continue;
	287	+ }
	288	+ add_action(
	289	+ $hook,
	290	+ static function () use ( $hook ): void {
	291	+ self::purge_all(
	292	+ 'hook:' . $hook,
	293	+ null,
	294	+ self::invalidation_for_hook( $hook )
	295	+ );
	296	+ }
	297	+ );
	298	+ // No purge_minified() here. Minified and combined files are named
	299	+ // by content, so a render after this purge links the same names
	300	+ // when nothing changed and new names when something did. Deleting
	301	+ // them only opened a window where cached and in-flight pages link
	302	+ // files that are gone, and on a network it took every subsite's
	303	+ // files with it.
44	304	}
45	305
	306	+ // Updating a plugin, theme or core changes the markup and the assets
	307	+ // a page is built from, but fires NONE of the hooks above: WordPress
	308	+ // does not deactivate and reactivate a plugin to update it, so
	309	+ // `activated_plugin` never runs and the cached HTML survives the
	310	+ // update untouched for the whole TTL — up to 7 days on the Aggressive
	311	+ // preset, 30 at the maximum.
	312	+ //
	313	+ // The stale copy is not merely old, it is wrong in a way the user
	314	+ // cannot see the cause of: they update a plugin to get a fix, the
	315	+ // cache keeps serving the pre-fix HTML, and the update looks like it
	316	+ // did nothing. Minified assets do regenerate on their own (they are
	317	+ // named by content), which makes it worse rather than better — the
	318	+ // cached pages still link the PREVIOUS names.
	319	+ //
	320	+ // Purge unconditionally on any completed update. Scoping it to
	321	+ // "plugins that enqueue front-end assets" is not knowable here, and a
	322	+ // cold cache after an update is the cheaper mistake. (#269)
	323	+ add_action( 'upgrader_process_complete', array( __CLASS__, 'purge_after_upgrade' ), 10, 2 );
	324	+ // The replacement signal has to outlive OUR listener: add-ons read it
	325	+ // through upgrade_replaced_code() from their own priority-10 callbacks,
	326	+ // and consuming it inside purge_after_upgrade() meant whoever
	327	+ // registered second saw false. Cleared at the END of the dispatch
	328	+ // instead, once every listener has had its turn.
	329	+ //
	330	+ // Depth-counted, because this action NESTS. Core hangs
	331	+ // Language_Pack_Upgrader::async_upgrade() on it at priority 20
	332	+ // (wp-admin/includes/admin-filters.php), and that runs a whole
	333	+ // upgrader of its own, which fires this same action again. A flat
	334	+ // reset therefore fired while the OUTER dispatch was still running —
	335	+ // on any site with pending translations — and every listener after
	336	+ // priority 20 read the cleared signal as false. Which is the bug this
	337	+ // pair exists to fix, back again and harder to see. (#303)
	338	+ add_action( 'upgrader_process_complete', array( __CLASS__, 'note_upgrade_dispatch' ), PHP_INT_MIN );
	339	+ add_action( 'upgrader_process_complete', array( __CLASS__, 'forget_cleared_destination' ), PHP_INT_MAX );
	340	+ // WordPress labels an upload-and-replace as an INSTALL, so the action
	341	+ // alone cannot tell "added beside nothing" from "replaced live code".
	342	+ // This filter fires only when the upgrader removed an existing copy,
	343	+ // which is exactly the difference. Registered as a filter listener
	344	+ // that returns its input untouched. (#303)
	345	+ add_filter( 'upgrader_clear_destination', array( __CLASS__, 'note_cleared_destination' ), 10, 4 );
	346	+ // …but `upgrader_clear_destination` fires whenever the upgrader was
	347	+ // ASKED to clear, not only when it removed something:
	348	+ // WP_Upgrader::clear_destination() returns true early when the
	349	+ // destination does not exist. Looked at before the delete, while the
	350	+ // old copy is still on disk. (#303)
	351	+ //
	352	+ // PHP_INT_MAX, because the folder name is only final once every other
	353	+ // listener has had its turn. Update libraries that normalise
	354	+ // `plugin-1.2.3/` to `plugin/` (Plugin Update Checker, EDD Software
	355	+ // Licensing, GitHub-sourced zips) rename the extracted directory on
	356	+ // this same filter at priority 10 or later, and core derives the real
	357	+ // destination from the FILTERED source. Measured at 10, a genuine
	358	+ // replacement read as "nothing was there" and the stale cache stayed.
	359	+ // note_cleared_destination() cross-checks the folder core actually
	360	+ // cleared against the one measured here, for a renamer that runs
	361	+ // later still. (#407 QA)
	362	+ add_filter( 'upgrader_source_selection', array( __CLASS__, 'note_destination_state' ), PHP_INT_MAX, 4 );
	363	+ // Unattended auto-updates are the case that matters most here: they
	364	+ // land overnight with nobody around to purge by hand, which is the
	365	+ // exact scenario the stale cache goes undiagnosed in. WordPress fires
	366	+ // this INSTEAD of a per-item upgrader_process_complete for some
	367	+ // background runs. Its payload is a results array keyed by type
	368	+ // rather than a hook_extra, so it needs its own handler — passing it
	369	+ // to purge_after_upgrade() landed it in the unused $upgrader slot and
	370	+ // left $type empty, which read as "invalidating" and purged the whole
	371	+ // cache for a language-pack-only run. Matches what LiteSpeed binds.
	372	+ // (#298)
	373	+ add_action( 'automatic_updates_complete', array( __CLASS__, 'purge_after_auto_updates' ), 10, 1 );
	374	+ // A Customizer publish changes theme mods, Additional CSS, the site
	375	+ // identity and widget areas, so markup and inline CSS change on every
	376	+ // page. It fires none of the hooks above. theme_mods_* is an ordinary
	377	+ // option, and Additional CSS is a non-viewable `custom_css` post that
	378	+ // the save_post gate rightly ignores. Without this, cached pages kept
	379	+ // the old header, colours and custom CSS for the whole TTL.
	380	+ add_action( 'customize_save_after', array( __CLASS__, 'on_customize_save' ), 10, 0 );
	381	+ // Adding, removing or editing a widget on the Widgets screen (classic
	382	+ // or block) only writes options: `sidebars_widgets` for which widget
	383	+ // sits where, `widget_<type>` for its settings. No hook above fires,
	384	+ // so the sidebar on every cached page stayed as it was until expiry.
	385	+ add_action( 'update_option_sidebars_widgets', array( __CLASS__, 'on_widgets_change' ), 10, 0 );
	386	+ add_action( 'add_option_sidebars_widgets', array( __CLASS__, 'on_widgets_change' ), 10, 0 );
	387	+ add_action( 'updated_option', array( __CLASS__, 'on_widget_option_change' ), 10, 1 );
	388	+ // …except the four hooks above that fire on ordinary visitor actions.
	389	+ // Attached bare, purge_all() can't see WHAT changed, so on a store
	390	+ // every order, every product review and every checkout
	391	+ // account-creation wiped 100% of the cache — all anonymous happy-path
	392	+ // actions, so the cache never reached steady state (#243). Measured:
	393	+ // 3 orders across 36 pageviews took the hit rate from 83% to 50% and
	394	+ // the average response from 23ms to 57ms.
	395	+ //
	396	+ // HPOS does NOT help: WooCommerce still writes a
	397	+ // `shop_order_placehold` row into wp_posts to reserve the order ID,
	398	+ // so save_post fires either way. The gate therefore keys on POST-TYPE
	399	+ // VIEWABILITY, not on storage mode — which fixes both modes at once,
	400	+ // and generalises to Flamingo (#229) and Tutor LMS (#231) too.
	401	+ remove_action( 'save_post', array( __CLASS__, 'purge_all' ) );
	402	+ add_action( 'save_post', array( __CLASS__, 'on_save_post' ), 10, 2 );
	403	+ // Bracket every post save, so a WooCommerce product save that runs
	404	+ // inside one (wp-admin's Update) can tell on_save_post() is about to
	405	+ // clear the whole site for the same product. See purge_product().
	406	+ add_action( 'save_post', array( __CLASS__, 'on_post_save_start' ), 0, 2 );
	407	+ add_action( 'save_post', array( __CLASS__, 'on_post_save_end' ), PHP_INT_MAX, 1 );
	408	+ // The narrow purge runs here, after the REST API has set the terms
	409	+ // (it sets them after `save_post`), with the post as it was before.
	410	+ add_action( 'wp_after_insert_post', array( __CLASS__, 'on_after_insert_post' ), 10, 4 );
	411	+ add_action( 'shutdown', array( __CLASS__, 'flush_pending_saves' ), 1, 0 );
	412	+ add_action( 'update_option_sticky_posts', array( __CLASS__, 'on_sticky_posts_change' ), 10, 2 );
	413	+ // The first sticky post on a site creates the option instead.
	414	+ add_action( 'add_option_sticky_posts', array( __CLASS__, 'on_sticky_posts_added' ), 10, 2 );
	415	+ add_action( 'pre_post_update', array( __CLASS__, 'on_pre_post_update' ), 10, 2 );
	416	+ add_action( 'before_delete_post', array( __CLASS__, 'on_post_removed' ), 10, 2 );
	417	+ add_action( 'trashed_post', array( __CLASS__, 'on_post_removed' ), 10, 2 );
	418	+ // wp_delete_post() hands an attachment to wp_delete_attachment() and
	419	+ // returns BEFORE before_delete_post fires, so deleting media reached
	420	+ // neither hook above. Attachment pages are public and media appears in
	421	+ // galleries, so that left cached pages showing a file that is gone.
	422	+ // (dev caught this via `deleted_post`, which this branch replaced.)
	423	+ add_action( 'delete_attachment', array( __CLASS__, 'on_post_removed' ), 10, 2 );
	424	+
	425	+ remove_action( 'comment_post', array( __CLASS__, 'purge_all' ) );
	426	+ add_action( 'comment_post', array( __CLASS__, 'on_comment_post' ), 10, 3 );
	427	+ add_action( 'wp_set_comment_status', array( __CLASS__, 'on_comment_status' ), 10, 2 );
	428	+
	429	+ remove_action( 'user_register', array( __CLASS__, 'purge_all' ) );
	430	+ add_action( 'user_register', array( __CLASS__, 'on_user_change' ) );
	431	+
	432	+ remove_action( 'profile_update', array( __CLASS__, 'purge_all' ) );
	433	+ add_action( 'profile_update', array( __CLASS__, 'on_user_change' ) );
	434	+
	435	+ // Product data lives in post meta and lookup tables, NOT in wp_posts,
	436	+ // so WC_Product_Data_Store_CPT::update() takes a direct $wpdb->update()
	437	+ // branch and save_post never fires. Anchoring invalidation on
	438	+ // save_post therefore missed 100% of commerce-relevant mutations: a
	439	+ // REST price change, wc_update_product_stock(), a CLI ->save(), and
	440	+ // every scheduled sale start/end left the product page, the shop and
	441	+ // the category archives serving the old price and stock for the full
	442	+ // lifetime — the store quoting one price and charging another (#242).
	443	+ //
	444	+ // This MUST ship with the gate above: once orders stop purging
	445	+ // everything, the accidental invalidation that was masking this
	446	+ // disappears, and an order that reduces stock would leave the product
	447	+ // page stale.
	448	+ if ( class_exists( 'WooCommerce' ) ) {
	449	+ foreach ( array( 'woocommerce_update_product', 'woocommerce_new_product' ) as $wc_hook ) {
	450	+ add_action( $wc_hook, array( __CLASS__, 'on_product_saved' ) );
	451	+ }
	452	+ // wc_update_product_stock() writes the stock with SQL, saves the
	453	+ // product (which fires woocommerce_update_product above), then
	454	+ // fires *_set_stock. The *_before_set_stock actions open that
	455	+ // write, so the *_set_stock that closes it can tell the save
	456	+ // inside it already purged. With `$updating` set it skips the
	457	+ // save, and *_set_stock is then the only purge.
	458	+ add_action( 'woocommerce_product_before_set_stock', array( __CLASS__, 'on_product_stock_write' ) );
	459	+ add_action( 'woocommerce_variation_before_set_stock', array( __CLASS__, 'on_product_stock_write' ) );
	460	+ add_action( 'woocommerce_product_set_stock', array( __CLASS__, 'on_product_stock_set' ) );
	461	+ add_action( 'woocommerce_variation_set_stock', array( __CLASS__, 'on_product_stock_set' ) );
	462	+ add_action( 'woocommerce_product_set_stock_status', array( __CLASS__, 'purge_product' ) );
	463	+ add_action( 'woocommerce_variation_set_stock_status', array( __CLASS__, 'purge_product' ) );
	464	+ }
	465	+
46	466	add_action( 'update_option_xspeed_options', array( __CLASS__, 'on_settings_change' ), 10, 2 );
47	467
	468	+ // …and the same for every PER-MODULE option. The handler above only
	469	+ // ever watched the legacy `xspeed_options` blob, but every module has
	470	+ // since migrated to its own `xspeed_module_<slug>` option and no hook
	471	+ // followed — so changing Minify HTML, Lazy Load, Remove Query Strings
	472	+ // etc. left the cached HTML untouched until the TTL expired (24h by
	473	+ // default) and the feature read as broken. (#205)
	474	+ //
	475	+ // One central listener rather than a hook per module: it covers Pro
	476	+ // modules with no cross-repo change, and a new module can't forget to
	477	+ // wire it up.
	478	+ add_action( 'updated_option', array( __CLASS__, 'on_module_settings_change' ), 10, 1 );
	479	+ // `added_option` matters as much as `updated_option`: on a fresh install
	480	+ // a module's option doesn't exist yet, so the FIRST save of every panel
	481	+ // goes through add_option() and would otherwise skip the purge — the
	482	+ // original bug surviving one save per module. `deleted_option` covers a
	483	+ // reset-to-defaults, which changes rendered HTML just as much. (#205)
	484	+ add_action( 'added_option', array( __CLASS__, 'on_module_settings_change' ), 10, 1 );
	485	+ add_action( 'deleted_option', array( __CLASS__, 'on_module_settings_change' ), 10, 1 );
	486	+
48	487	add_action( 'admin_bar_menu', array( $this, 'admin_bar_purge' ), 100 );
49	488	add_action( 'admin_post_xspeed_purge', array( $this, 'handle_admin_bar_purge' ) );
50	489	}
51	490
		@@ -56,23 +495,1503 @@
56	495	// (Cache module). Keep this handler around for whatever still
57	496	// lives in the legacy blob (cache_enabled is special and goes
58	497	// through Cache::toggle anyway).
59	498
60		- // Any settings change — purge caches so changes take effect.
	499	+ // Any settings change — purge caches so changes take effect. Minified
	500	+ // files are named by content, so there is nothing to delete for them.
61	501	self::purge_all( 'settings change' );
62		- Minifier::purge_minified();
63	502	}
64	503
	504	+ /**
	505	+ * Modules whose settings cannot change rendered HTML, so a write to them
	506	+ * doesn't warrant throwing away the page cache.
	507	+ *
	508	+ * The safe default is to purge: a module is listed here only when it is
	509	+ * clearly incapable of altering front-end output (diagnostics, the MCP
	510	+ * server, licensing/telemetry surfaces). When in doubt, leave it off the
	511	+ * list — a needless purge costs a re-render, a missed one makes the
	512	+ * feature look broken. (#205)
	513	+ *
	514	+ * @return string[] Module slugs.
	515	+ */
	516	+ public static function non_rendering_modules(): array {
	517	+ return (array) apply_filters(
	518	+ 'xspeed_non_rendering_modules',
	519	+ array(
	520	+ 'mcp', // AI endpoint — no front-end output.
	521	+ 'health', // diagnostics only.
	522	+ 'support', // support snapshot.
	523	+ 'score', // PageSpeed/GTmetrix runner.
	524	+ 'migration', // one-shot importer.
	525	+ 'settings', // import/export surface.
	526	+ 'cache-coverage', // read-only reporting.
	527	+ 'ai-privacy', // consent flags for AI surfaces.
	528	+ 'database', // DB cleanup schedule — no HTML impact.
	529	+ // Pro slugs — listed by name rather than by asking Pro, so
	530	+ // Free stays unaware of it. A Pro module absent here simply
	531	+ // purges, which is the safe default.
	532	+ 'license',
	533	+ 'pro_status',
	534	+ 'analytics',
	535	+ 'performance-health',
	536	+ 'recommendations',
	537	+ 'ai-provider',
	538	+ 'migration-pro',
	539	+ )
	540	+ );
	541	+ }
	542	+
	543	+ /**
	544	+ * Purge when ANY module's settings option is written. (#205)
	545	+ *
	546	+ * Bound to `updated_option`, `added_option` and `deleted_option` — all three
	547	+ * fire for every option on the site, so the prefix test comes first and is
	548	+ * the cheap path for the ~99% of writes that aren't ours. All three pass the
	549	+ * option name first, which is why this can't hook purge_all() directly:
	550	+ * that takes $cause first, so every purge would be filed under a cause
	551	+ * literally named "xspeed_module_minify".
	552	+ *
	553	+ * @param string $option Option name that was just written or removed.
	554	+ */
	555	+ public static function on_module_settings_change( $option ): void {
	556	+ $option = (string) $option;
	557	+ $prefix = Settings_Manager::OPTION_PREFIX;
	558	+ if ( 0 !== strpos( $option, $prefix ) ) {
	559	+ return;
	560	+ }
	561	+
	562	+ $slug = substr( $option, strlen( $prefix ) );
	563	+ if ( '' === $slug || in_array( $slug, self::non_rendering_modules(), true ) ) {
	564	+ return;
	565	+ }
	566	+
	567	+ // Guard against re-entry: purge_all() can write options of its own (stats, timestamps), and a nested purge would
	568	+ // both waste work and risk recursing through this same hook.
	569	+ static $purging = false;
	570	+ if ( $purging ) {
	571	+ return;
	572	+ }
	573	+ $purging = true;
	574	+
	575	+ self::purge_all( 'settings change' );
	576	+
	577	+ $purging = false;
	578	+ }
	579	+
	580	+ /**
	581	+ * Stamp the request's cache decision on the response.
	582	+ *
	583	+ * `X-XSpeed-Cache` was only ever written on the serve-from-cache paths,
	584	+ * so a miss and a deliberate bypass both came back with no header at all
	585	+ * — indistinguishable from a `curl -I`, the first thing anyone reaches
	586	+ * for when a site "isn't caching" (issue #10). The reason slug rides
	587	+ * along on `X-XSpeed-Reason`, but only under WP_DEBUG so production
	588	+ * responses stay clean. Slugs are fixed per gate — never the matched
	589	+ * pattern, cookie or user-agent, which would echo request input back.
	590	+ *
	591	+ * @param string $value HIT (php) | MISS | BYPASS.
	592	+ * @param string $reason Fixed slug naming the gate, for BYPASS only.
	593	+ * @param int|null $lifetime_left On a HIT, the seconds the served entry has
	594	+ * left when it has a lifetime of its own;
	595	+ * null when it follows the site's. See
	596	+ * entry_lifetime_left().
	597	+ */
	598	+ private static function mark( string $value, string $reason = '', ?int $lifetime_left = null ): void {
	599	+ self::$status_header = $value;
	600	+ self::$bypass_reason = $reason;
	601	+ self::$edge_headers = array();
	602	+
	603	+ // A served-from-cache response may carry edge/CDN headers an add-on
	604	+ // contributes — `CDN-Cache-Control`, `Cache-Tag` and friends. Only a
	605	+ // HIT resolves them here. A BYPASS never does: the response was
	606	+ // deliberately excluded from our cache, so telling a CDN to hold it
	607	+ // for a month would cache at the edge exactly what we refused to
	608	+ // cache here. A MISS never does either, stored or not: it is the
	609	+ // first render, and the one most likely to be replaced once critical
	610	+ // CSS and unused CSS have been generated. Pinning it at the edge pins
	611	+ // the version xSpeed is about to improve on. The edge caches from the
	612	+ // first HIT instead — one render later, and the right one.
	613	+ //
	614	+ // Resolved before the headers_sent() guard so the decision is
	615	+ // recorded (and observable in tests) even on a request that can no
	616	+ // longer send headers; only the emission below is conditional.
	617	+ if ( 'HIT' === self::edge_status( $value ) ) {
	618	+ self::$edge_headers = self::edge_headers_for( 'HIT' );
	619	+ }
	620	+
	621	+ // Every status, not just a HIT. A page we declined to cache is the
	622	+ // one an edge most needs telling about: it goes out naked today, and
	623	+ // a CDN that stores HTML by default keeps somebody's cart.
	624	+ //
	625	+ // Resolved before the headers_sent() guard so the decision is
	626	+ // recorded (and observable in tests) even on a request that can no
	627	+ // longer send headers; only the emission below is conditional.
	628	+ self::$edge_headers = self::edge_headers_for( self::edge_status( $value ), 'request', $reason );
	629	+
	630	+ // The same countdown the drop-in applies to this entry, so the two
	631	+ // PHP serve paths tell the edge the same thing about one page.
	632	+ if ( null !== $lifetime_left && 'HIT' === self::edge_status( $value ) ) {
	633	+ self::$edge_headers = self::cap_edge_lifetime( self::$edge_headers, $lifetime_left );
	634	+ }
	635	+
	636	+ if ( headers_sent() ) {
	637	+ return;
	638	+ }
	639	+ header( 'X-XSpeed-Cache: ' . $value );
	640	+ if ( '' !== $reason && defined( 'WP_DEBUG' ) && WP_DEBUG ) {
	641	+ header( 'X-XSpeed-Reason: ' . $reason );
	642	+ }
	643	+ foreach ( self::$edge_headers as $name => $val ) {
	644	+ header( $name . ': ' . $val );
	645	+ }
	646	+ }
	647	+
	648	+ /**
	649	+ * Normalize an `X-XSpeed-Cache` value to the vocabulary the edge seam
	650	+ * speaks.
	651	+ *
	652	+ * The header value carries which layer served the page (`HIT (php)`,
	653	+ * `HIT (nginx)`, `HIT (static)`); nothing deciding what to tell a CDN
	654	+ * cares, and making a caller match on three spellings of one outcome is
	655	+ * how a rule ends up applied on two paths out of three.
	656	+ */
	657	+ private static function edge_status( string $value ): string {
	658	+ return 0 === strpos( $value, 'HIT' ) ? 'HIT' : $value;
	659	+ }
	660	+
	661	+ /**
	662	+ * Hash a generated rule set so the rules can identify themselves.
	663	+ *
	664	+ * @param string[] $lines Every line of the rule set EXCEPT the marker.
	665	+ */
	666	+ private static function rules_hash( array $lines ): string {
	667	+ return substr( sha1( implode( "\n", $lines ) ), 0, 8 );
	668	+ }
	669	+
	670	+ /**
	671	+ * Insert the self-describing marker directive into a generated rule set.
	672	+ *
	673	+ * The hash is taken over the rule set WITHOUT this line, and that is the
	674	+ * whole trick: hashing the finished text instead would mean the act of
	675	+ * adding the marker changed the value the marker advertises, the probe
	676	+ * would never see a match, and every correctly installed block would
	677	+ * report itself out of date forever. The one property worth a test of its
	678	+ * own — RewriteProbeRulesStateTest covers it.
	679	+ *
	680	+ * More than one template is allowed because Apache needs the same marker
	681	+ * twice, under two environment-variable names (see rewrite_block_lines).
	682	+ * All of them carry the SAME hash, taken over the marker-less rule set, so
	683	+ * adding the second directive cannot change the value either advertises.
	684	+ *
	685	+ * @param string[] $lines The rule set, with no marker line in it.
	686	+ * @param string[] $templates sprintf templates for the directives; `%s` is the hash.
	687	+ * @param int $at Index to insert the marker at.
	688	+ * @return string[]
	689	+ */
	690	+ private static function with_rules_marker( array $lines, array $templates, int $at ): array {
	691	+ $hash = self::rules_hash( $lines );
	692	+ $directives = array();
	693	+ foreach ( $templates as $template ) {
	694	+ $directives[] = sprintf( $template, $hash );
	695	+ }
	696	+ array_splice( $lines, $at, 0, $directives );
	697	+ return $lines;
	698	+ }
	699	+
	700	+ /**
	701	+ * The rules hash the CURRENT settings generate, i.e. what a correctly
	702	+ * installed rule set would be sending back.
	703	+ *
	704	+ * Read out of the generated artifact rather than recomputed, so there is
	705	+ * exactly one definition of the hash and no way for the generator and the
	706	+ * expectation to drift apart. Empty on a server whose fast path we do not
	707	+ * generate rules for.
	708	+ */
	709	+ public static function rules_marker_expected(): string {
	710	+ $type = Server::type();
	711	+ if ( Server::NGINX === $type ) {
	712	+ return self::extract_rules_marker( (string) self::nginx_snippet() );
	713	+ }
	714	+ if ( Server::APACHE === $type ) {
	715	+ return self::extract_rules_marker( implode( "\n", self::rewrite_block_lines() ) );
	716	+ }
	717	+ return '';
	718	+ }
	719	+
	720	+ /** Pull the marker value out of a generated rule set ('' when absent). */
	721	+ public static function extract_rules_marker( string $source ): string {
	722	+ if ( preg_match( '/' . preg_quote( self::RULES_HEADER, '/' ) . ' "([0-9a-f]{8})"/', $source, $m ) ) {
	723	+ return $m[1];
	724	+ }
	725	+ return '';
	726	+ }
	727	+
	728	+ /**
	729	+ * Fingerprint of every setting that feeds the generated server rules.
	730	+ *
	731	+ * Values are hashed rather than stored: this map is written from a read
	732	+ * path and has no business becoming a second copy of the user's exclusion
	733	+ * lists. A per-key hash is enough — the point is to name WHICH setting
	734	+ * moved between two rule versions, not to reconstruct the old value.
	735	+ *
	736	+ * @return array<string,string>
	737	+ */
	738	+ public static function rules_inputs(): array {
	739	+ $cache_opts = Settings_Manager::get( 'cache' );
	740	+ $fingerprint = static function ( $value ): string {
	741	+ $flat = array();
	742	+ foreach ( (array) $value as $key => $item ) {
	743	+ $flat[] = $key . '=' . ( is_scalar( $item ) ? (string) $item : '' );
	744	+ }
	745	+ return substr( sha1( implode( "\x1f", $flat ) ), 0, 8 );
	746	+ };
	747	+
	748	+ return array(
	749	+ 'excluded_cookies' => $fingerprint( $cache_opts['excluded_cookies'] ?? array() ),
	750	+ 'bypass_user_agents' => $fingerprint( $cache_opts['bypass_user_agents'] ?? array() ),
	751	+ 'excluded_urls' => $fingerprint( $cache_opts['excluded_urls'] ?? array() ),
	752	+ 'edge_headers' => $fingerprint( self::edge_headers_for( 'HIT', 'rules' ) ),
	753	+ 'static_dir' => $fingerprint( array( XSPEED_CACHE_STATIC_DIR ) ),
	754	+ );
	755	+ }
	756	+
	757	+ /**
	758	+ * Remember which settings produced a rules version.
	759	+ *
	760	+ * Without this a stale verdict can only say "stale". With it, the hash the
	761	+ * server sent back is a key into what the site's settings looked like when
	762	+ * those rules were generated, so the dashboard can name what changed since
	763	+ * the user last pasted. Bounded to the last few versions — the map exists
	764	+ * to explain a recent drift, not to keep a history.
	765	+ *
	766	+ * @param array<string,string> $inputs Fingerprint from rules_inputs().
	767	+ */
	768	+ private static function remember_rules_inputs( string $hash, array $inputs ): void {
	769	+ if ( '' === $hash ) {
	770	+ return;
	771	+ }
	772	+ $map = get_option( self::RULES_INPUTS_OPTION, array() );
	773	+ if ( ! is_array( $map ) ) {
	774	+ $map = array();
	775	+ }
	776	+ if ( isset( $map[ $hash ] ) && $map[ $hash ] === $inputs ) {
	777	+ return;
	778	+ }
	779	+ $map[ $hash ] = $inputs;
	780	+ if ( count( $map ) > self::RULES_INPUTS_KEPT ) {
	781	+ $map = array_slice( $map, -self::RULES_INPUTS_KEPT, null, true );
	782	+ }
	783	+ update_option( self::RULES_INPUTS_OPTION, $map, false );
	784	+ }
	785	+
	786	+ /**
	787	+ * Which settings changed between the installed rules and the current ones.
	788	+ *
	789	+ * Empty when the installed version predates the map (nothing to compare
	790	+ * against) — the caller then says "out of date" without naming a cause,
	791	+ * which is honest.
	792	+ *
	793	+ * @param array<string,string> $current Fingerprint from rules_inputs().
	794	+ * @return string[] Setting keys.
	795	+ */
	796	+ private static function changed_rules_inputs( string $observed, array $current ): array {
	797	+ $map = get_option( self::RULES_INPUTS_OPTION, array() );
	798	+ if ( ! is_array( $map ) || ! isset( $map[ $observed ] ) || ! is_array( $map[ $observed ] ) ) {
	799	+ return array();
	800	+ }
	801	+
	802	+ $was = $map[ $observed ];
	803	+ $changed = array();
	804	+ foreach ( $current as $key => $value ) {
	805	+ if ( ! array_key_exists( $key, $was ) || $was[ $key ] !== $value ) {
	806	+ $changed[] = $key;
	807	+ }
	808	+ }
	809	+ return $changed;
	810	+ }
	811	+
	812	+ /**
	813	+ * Whether the rules the server is running are the rules these settings
	814	+ * generate.
	815	+ *
	816	+ * Nothing in WordPress can read a hand-pasted nginx server block, so
	817	+ * before this the dashboard could only guess — and guessed by telling
	818	+ * everyone to re-paste after every settings change. The generated rules
	819	+ * now carry their own hash and the probe reads it back:
	820	+ *
	821	+ * current — the marker matches what these settings generate.
	822	+ * stale — a marker came back, from a different version of the rules.
	823	+ * absent — the probe reached a verdict and saw no marker: either no
	824	+ * rules are installed (the request fell through to PHP) or
	825	+ * they predate the marker. Either way the fix is the same.
	826	+ * unknown — the probe could not tell, or this server has no rule set we
	827	+ * generate.
	828	+ *
	829	+ * A marker outranks the probe's own `active` verdict: the marker is direct
	830	+ * evidence of which rules answered, while `active` is inferred from
	831	+ * response shape.
	832	+ *
	833	+ * Scope: the static-cache rules only — nginx_snippet() on nginx, the
	834	+ * .htaccess block on Apache. full_nginx_server_block() pastes those
	835	+ * alongside other modules' directives, and a change to one of those does
	836	+ * NOT move this hash. Hashing the aggregate would mean the marker inside
	837	+ * the location block had to know the text it is embedded in, and the
	838	+ * snippet would hash differently depending on which caller asked for it.
	839	+ * Callers wording this for a human should say "cache rules", not "your
	840	+ * nginx config".
	841	+ *
	842	+ * `copied` is the mirror of what this admin last pasted — see
	843	+ * rules_copied(). It is always present, null included, because a client
	844	+ * keys on the key existing to decide whether the server remembers at all.
	845	+ *
	846	+ * @param array $probe Raw result from probe_static_rewrite().
	847	+ * @return array{expected:string,observed:string,state:string,changed:string[],copied:array{hash:string,at:int}|null}
	848	+ */
	849	+ public static function rules_state( array $probe ): array {
	850	+ $expected = self::rules_marker_expected();
	851	+ $observed = (string) ( $probe['rules'] ?? '' );
	852	+ $copied = self::rules_copied();
	853	+
	854	+ if ( '' === $expected ) {
	855	+ return array(
	856	+ 'expected' => '',
	857	+ 'observed' => $observed,
	858	+ 'state' => 'unknown',
	859	+ 'changed' => array(),
	860	+ 'copied' => $copied,
	861	+ );
	862	+ }
	863	+
	864	+ $inputs = self::rules_inputs();
	865	+ self::remember_rules_inputs( $expected, $inputs );
	866	+
	867	+ if ( '' !== $observed ) {
	868	+ return array(
	869	+ 'expected' => $expected,
	870	+ 'observed' => $observed,
	871	+ 'state' => $observed === $expected ? 'current' : 'stale',
	872	+ 'changed' => $observed === $expected ? array() : self::changed_rules_inputs( $observed, $inputs ),
	873	+ 'copied' => $copied,
	874	+ );
	875	+ }
	876	+
	877	+ // `absent` is a claim about what is installed, so it takes a probe that
	878	+ // completed a round trip and read the response headers. A result that
	879	+ // is still pending, one whose loopback failed, one a CDN answered, and
	880	+ // one that never got off the ground (no host in home_url, no writable
	881	+ // probe dir — neither of which sets `inconclusive`, and both of which
	882	+ // arrive here with no status code) all leave us knowing nothing.
	883	+ if ( empty( $probe['code'] ) || ! empty( $probe['pending'] ) || ! empty( $probe['inconclusive'] ) ) {
	884	+ return array(
	885	+ 'expected' => $expected,
	886	+ 'observed' => '',
	887	+ 'state' => 'unknown',
	888	+ 'changed' => array(),
	889	+ 'copied' => $copied,
	890	+ );
	891	+ }
	892	+
	893	+ return array(
	894	+ 'expected' => $expected,
	895	+ 'observed' => '',
	896	+ 'state' => 'absent',
	897	+ 'changed' => array(),
	898	+ 'copied' => $copied,
	899	+ );
	900	+ }
	901	+
	902	+ /**
	903	+ * Which version of the rules this admin says they pasted into the server.
	904	+ *
	905	+ * Their claim, not evidence — the probe is the evidence, and where the
	906	+ * probe can answer this is ignored. It exists for the `unknown` state: a
	907	+ * host whose loopback is blocked, or one behind a CDN that answers the
	908	+ * probe itself, where nothing can read back what is installed. There the
	909	+ * only thing left to go on is that someone said they had done it, and
	910	+ * without a record of that the panel asks every admin to paste the block
	911	+ * again forever.
	912	+ *
	913	+ * Per user rather than per site, because it is a claim a person made. A
	914	+ * second admin on the same site has not pasted anything and should not be
	915	+ * told the work is done. Null when nobody has claimed this version, when
	916	+ * the stored value is not a shape we wrote, or when there is no current
	917	+ * user at all (WP-CLI, cron).
	918	+ *
	919	+ * @return array{hash:string,at:int}|null
	920	+ */
	921	+ public static function rules_copied(): ?array {
	922	+ if ( ! function_exists( 'get_current_user_id' ) || ! function_exists( 'get_user_meta' ) ) {
	923	+ return null;
	924	+ }
	925	+ $user_id = (int) get_current_user_id();
	926	+ if ( $user_id <= 0 ) {
	927	+ return null;
	928	+ }
	929	+
	930	+ $stored = get_user_meta( $user_id, self::RULES_COPIED_META, true );
	931	+ if ( ! is_array( $stored ) ) {
	932	+ return null;
	933	+ }
	934	+
	935	+ $hash = (string) ( $stored['hash'] ?? '' );
	936	+ $at = (int) ( $stored['at'] ?? 0 );
	937	+ if ( ! self::is_rules_hash( $hash ) || $at <= 0 ) {
	938	+ return null;
	939	+ }
	940	+
	941	+ return array(
	942	+ 'hash' => $hash,
	943	+ 'at' => $at,
	944	+ );
	945	+ }
	946	+
	947	+ /**
	948	+ * Record that this admin pasted the rules whose marker is $hash.
	949	+ *
	950	+ * Rejects anything that is not one of our markers rather than storing it,
	951	+ * so the mirror can only ever hold a value rules_marker_expected() could
	952	+ * also produce — a stored string that matches nothing would read as "a
	953	+ * different version is installed" forever.
	954	+ *
	955	+ * @param string $hash The 8-hex rules marker the admin copied.
	956	+ * @return array{hash:string,at:int}|null The stored record, or null if refused.
	957	+ */
	958	+ public static function remember_rules_copied( string $hash ): ?array {
	959	+ // Trimmed but not case-folded: extract_rules_marker() reads a marker
	960	+ // back in lower case only, so an upper-case claim would never match
	961	+ // anything the probe could observe. Refuse it rather than store a
	962	+ // value that can only ever read as a different version.
	963	+ $hash = trim( $hash );
	964	+ if ( ! self::is_rules_hash( $hash ) ) {
	965	+ return null;
	966	+ }
	967	+ if ( ! function_exists( 'get_current_user_id' ) || ! function_exists( 'update_user_meta' ) ) {
	968	+ return null;
	969	+ }
	970	+ $user_id = (int) get_current_user_id();
	971	+ if ( $user_id <= 0 ) {
	972	+ return null;
	973	+ }
	974	+
	975	+ $record = array(
	976	+ 'hash' => $hash,
	977	+ 'at' => time(),
	978	+ );
	979	+ update_user_meta( $user_id, self::RULES_COPIED_META, $record );
	980	+
	981	+ return $record;
	982	+ }
	983	+
	984	+ /** Whether a string is shaped like one of our rules markers. */
	985	+ public static function is_rules_hash( string $hash ): bool {
	986	+ return 1 === preg_match( '/^[0-9a-f]{8}$/', $hash );
	987	+ }
	988	+
	989	+ /** Record a bypass gate and answer "don't cache" in one statement. */
	990	+ private static function bypass( string $reason ): bool {
	991	+ self::mark( 'BYPASS', $reason );
	992	+ return false;
	993	+ }
	994	+
	995	+ /** The X-XSpeed-Cache value decided for this request ('' if none yet). */
	996	+ public static function status_header(): string {
	997	+ return self::$status_header;
	998	+ }
	999	+
	1000	+ /** The bypass gate slug for this request ('' unless BYPASS). */
	1001	+ public static function bypass_reason(): string {
	1002	+ return self::$bypass_reason;
	1003	+ }
	1004	+
	1005	+ /**
	1006	+ * The edge/CDN pairs sent on this request ('' if none were).
	1007	+ *
	1008	+ * @return array<string,string>
	1009	+ */
	1010	+ public static function edge_headers(): array {
	1011	+ return self::$edge_headers;
	1012	+ }
	1013	+
	1014	+ /**
	1015	+ * Bypass gates that do NOT ask a cache in front of us to stand down.
	1016	+ *
	1017	+ * Every other slug does. The split is the reason this reads the gate
	1018	+ * rather than the status: a bypass usually means "this response is
	1019	+ * personal, or someone decided this page is never stored", and an edge
	1020	+ * holding one of those does precisely what we refused to do. These two
	1021	+ * mean something else.
	1022	+ *
	1023	+ * `cache-disabled` is the user switching OUR page cache off. Nothing
	1024	+ * about the page became personal. Sending `no-store` on every page of a
	1025	+ * site whose owner chose a different cache would make a local toggle a
	1026	+ * site-wide side effect on infrastructure we do not own.
	1027	+ *
	1028	+ * `non-frontend` is admin, REST, cron and AJAX. Not ours to describe:
	1029	+ * WordPress already nocaches admin, and a REST caller sets its own
	1030	+ * policy.
	1031	+ */
	1032	+ private const HOLD_EXEMPT_BYPASS = array( 'cache-disabled', 'non-frontend' );
	1033	+
	1034	+ /**
	1035	+ * Bypass gates that describe the SHAPE of the request rather than the
	1036	+ * visitor or the page.
	1037	+ *
	1038	+ * These still hold, but only once we have evidence of an edge — the same
	1039	+ * bar a MISS has to clear. The difference matters because the default
	1040	+ * excluded-URL list contains `/feed/`, the sitemap and `/wp-json/`, and
	1041	+ * `query-param` catches `?lang=fr`, `?paged=2`, and every page of a
	1042	+ * plain-permalink site.
	1043	+ *
	1044	+ * xSpeed refuses those because IT cannot key on a query string, not
	1045	+ * because the response is private. A CDN keys on the full URL and caches
	1046	+ * them correctly. Holding them unconditionally would have meant every
	1047	+ * default install stopped its feed and sitemap being edge-cached — a
	1048	+ * performance regression shipped to sites that never had a CDN in the
	1049	+ * first place, in the name of protecting them from one.
	1050	+ *
	1051	+ * The gates left out of this list are about the visitor (`logged-in`,
	1052	+ * `excluded-cookie`) or are somebody stating outright that this page is
	1053	+ * never to be stored (`donotcachepage`, `post-excluded`, `filtered`).
	1054	+ * Those hold whether or not we can see an edge.
	1055	+ */
	1056	+ private const REQUEST_SHAPE_BYPASS = array( 'query-param', 'non-get', 'user-agent' );
	1057	+
	1058	+ /**
	1059	+ * Default exclusions that are about the site's plumbing, not its content.
	1060	+ *
	1061	+ * `excluded-url` covers two unlike things. The default list carries
	1062	+ * `/cart`, `/checkout`, `/my-account` and `/wp-login` — personal pages,
	1063	+ * and the reason this feature exists. It also carries the entries below:
	1064	+ * feeds, sitemaps, the REST root, the front controller. Those are public,
	1065	+ * cacheable, and hammered by pollers; a CDN keys on the full URL and
	1066	+ * serves them correctly, so telling it to stop is a cost with no benefit.
	1067	+ *
	1068	+ * Matched as exact strings against the stored list, never as patterns
	1069	+ * against the path. Three bugs came out of doing it the other way round:
	1070	+ * `strpos( $uri, '/feed' )` matched `/my-account/feedback/`, reading the
	1071	+ * whole URI let `/cart/?utm_source=/feed/` disguise a cart as a feed, and
	1072	+ * a bare `index.php` — which is in this list, and which every URL contains
	1073	+ * on an "almost pretty" permalink site — made every page on such a site
	1074	+ * look personal. Comparing the LIST ENTRY rather than the path cannot make
	1075	+ * any of those mistakes, and it keeps a pattern the site owner added
	1076	+ * themselves on the personal side where it belongs.
	1077	+ */
	1078	+ private const STRUCTURAL_EXCLUSIONS = array(
	1079	+ '/wp-json/',
	1080	+ '/xmlrpc.php',
	1081	+ '~wp-.*\.php',
	1082	+ '/feed/',
	1083	+ 'index.php',
	1084	+ '/robots.txt',
	1085	+ // Both spellings, and no entry here is ever retired. This is a
	1086	+ // RECOGNITION list, not a source of truth: it is matched against
	1087	+ // whatever the site has STORED, and a site that saved its settings
	1088	+ // before `~sitemap(_index)?\.xml` was widened to `sitemaps?` (for
	1089	+ // SEOPress, which ships sitemaps.xml) still has the old string in
	1090	+ // its option row. Dropping the old spelling when the default moved
	1091	+ // would read every upgraded site's sitemap exclusion as somebody's
	1092	+ // personal data and hold sitemaps off the CDN — the bug this whole
	1093	+ // predicate exists to prevent, reintroduced by a rename.
	1094	+ '~sitemaps?(_index)?\.xml',
	1095	+ '~sitemap(_index)?\.xml',
	1096	+ );
	1097	+ /**
	1098	+ * Header names no edge instruction may ever carry.
	1099	+ *
	1100	+ * These describe the transfer, not the caching policy, and one wrong
	1101	+ * value from a settings field is a white screen rather than a missing
	1102	+ * optimization.
	1103	+ */
	1104	+ private const NEVER_AN_EDGE_HEADER = array(
	1105	+ 'content-length',
	1106	+ 'content-encoding',
	1107	+ 'content-type',
	1108	+ 'transfer-encoding',
	1109	+ 'set-cookie',
	1110	+ 'location',
	1111	+ 'x-xspeed-cache',
	1112	+ 'x-xspeed-edge-hold',
	1113	+ // `X-XSpeed-Built` says when THIS PAGE's HTML was generated, which is
	1114	+ // what a downstream verifier compares against the moment it asked for
	1115	+ // a purge. Free owns it and never takes it from a filter, in any
	1116	+ // context — see the BUILT_HEADER docblock.
	1117	+ //
	1118	+ // Under `bake` a supplied value would be frozen into an artifact and
	1119	+ // report when the artifact was written: identical on every page and
	1120	+ // never moving. Under `request` it is no better, because the filter
	1121	+ // runs from mark() with no file and no mtime in reach, so the only
	1122	+ // value anything can produce there is time() — the moment of the
	1123	+ // SERVE, not of the build. Both make every purge check pass.
	1124	+ //
	1125	+ // Free stamps the real value where it has the file: the drop-in and
	1126	+ // serve_not_modified(), both from filemtime(). The static serve paths
	1127	+ // run no PHP and carry no stamp at all; their `Last-Modified` is read
	1128	+ // instead.
	1129	+ 'x-xspeed-built',
	1130	+ );
	1131	+
	1132	+ /**
	1133	+ * Reasons that hold the edge off even when we detected nothing in front.
	1134	+ *
	1135	+ * `none` confidence means no evidence of a proxy, which is not proof
	1136	+ * there is none — a transparent proxy and a host page cache both leave
	1137	+ * the request untouched. So the question is what a wasted header costs
	1138	+ * against what a missed one does, and the answer differs by reason.
	1139	+ *
	1140	+ * These two are correctness failures. A cart page stored by something we
	1141	+ * could not see is the defect this exists to fix, and a mobile-split page
	1142	+ * served to the wrong device is a wrong page rather than a slow one.
	1143	+ * Ninety bytes on a response that was never cacheable is a cheap premium.
	1144	+ *
	1145	+ * `miss` and `pending` are performance hedges, and a hedge against a
	1146	+ * cache that does not exist is noise on every first render. Skipping them
	1147	+ * has a second benefit: because per_entry_edge_headers() compares `store`
	1148	+ * against `bake`, a `pending` hold that never fires leaves the two
	1149	+ * agreeing, which keeps the page on the static tree.
	1150	+ *
	1151	+ * `query-variant` waits for evidence as well. It is about purges. An edge
	1152	+ * keeps a separate copy for every query string, and a purge of the plain
	1153	+ * URL never reaches them. With no edge in front there are no copies.
	1154	+ */
	1155	+ private const HOLD_WITHOUT_EVIDENCE = array( 'bypass', 'mobile-split' );
	1156	+
	1157	+ /**
	1158	+ * True only while query_variant_edge_headers() bakes the drop-in's
	1159	+ * answer for a URL no purge names.
	1160	+ *
	1161	+ * A bake has no request to read, so this is how it asks "what if this
	1162	+ * HIT carried a param no purge names?". The drop-in answers that for
	1163	+ * itself, per request. Never true outside that one call.
	1164	+ *
	1165	+ * @var bool
	1166	+ */
	1167	+ private static $baking_query_variant = false;
	1168	+
	1169	+ /**
	1170	+ * Is a module still going to change this page after this response?
	1171	+ *
	1172	+ * Free itself never says yes — nothing in Free defers work past the
	1173	+ * request. Minification and combining write their file and return its URL
	1174	+ * inside the same render; the LCP preload is chosen by parsing the HTML
	1175	+ * being sent. It is the question that matters to anything caching in
	1176	+ * front of us, so Free asks it on their behalf and lets whoever owns the
	1177	+ * deferred work answer.
	1178	+ *
	1179	+ * Answer TRUE while the work is outstanding for the page being served.
	1180	+ * The cost of a false yes is one extra origin hit; the cost of a false no
	1181	+ * is an un-optimized page pinned at the edge for the full lifetime, which
	1182	+ * is the failure this exists to prevent — so when in doubt, say yes.
	1183	+ *
	1184	+ * Asked on a `request` only, and that boundary is the whole safety of it.
	1185	+ *
	1186	+ * A `bake` is generated once, in an admin or CLI request, and serves every
	1187	+ * static HIT on the site; a per-page answer frozen into it would be wrong
	1188	+ * for every other page.
	1189	+ *
	1190	+ * A `store` is worse, and cost a live site an afternoon. The pairs written
	1191	+ * at store time go into the `.meta` sidecar, which the drop-in replays on
	1192	+ * every later HIT — before plugins load, so nothing can re-ask this
	1193	+ * question. A hold written there therefore outlives the state that caused
	1194	+ * it, and the only thing that clears it is the page being stored again. On
	1195	+ * a site where the deferred work never completes, every re-store re-pins
	1196	+ * it, and the page is never edge-cacheable again. The symptom is a cache
	1197	+ * HIT carrying `no-store` and `X-XSpeed-Edge-Hold: pending` on a page
	1198	+ * whose deferred work finished long ago — the sidecar answering with
	1199	+ * state nothing can re-ask.
	1200	+ *
	1201	+ * Holding the MISS is what this is for, and it is enough: that response is
	1202	+ * the un-optimized one. The copy we then store is what an edge should
	1203	+ * mirror, and when the work does land the module purges the page, which
	1204	+ * reaches the edge. The purge is the correctness mechanism; this is only
	1205	+ * meant to cover the single render before it.
	1206	+ *
	1207	+ * @param string $context `request`, `store` or `bake`.
	1208	+ */
	1209	+ public static function edge_optimization_pending( string $context = 'request' ): bool {
	1210	+ if ( 'request' !== $context ) {
	1211	+ return false;
	1212	+ }
	1213	+
	1214	+ /**
	1215	+ * Filter: xspeed_edge_optimization_pending
	1216	+ *
	1217	+ * @param bool $pending Whether deferred work will still change this page.
	1218	+ */
	1219	+ return (bool) apply_filters( 'xspeed_edge_optimization_pending', false );
	1220	+ }
	1221	+
	1222	+ /**
	1223	+ * Does mobile cache split this URL into two renders?
	1224	+ *
	1225	+ * With `mobile_separate` on, Free keys its cache on device and serves a
	1226	+ * different page to a phone than to a desktop at the SAME url. No CDN
	1227	+ * varies on User-Agent, so an edge holding one of those renders serves it
	1228	+ * to everyone: whichever device asked first decides what the other sees,
	1229	+ * for the whole lifetime. A wrong page, not a slow one.
	1230	+ *
	1231	+ * Read from the stored option rather than through Settings_Manager: this
	1232	+ * is consulted from the serve path, where the module registry may not
	1233	+ * have run.
	1234	+ */
	1235	+ private static function mobile_cache_splits_html(): bool {
	1236	+ $stored = self::stored_cache_opts();
	1237	+ return ! empty( $stored['mobile_separate'] );
	1238	+ }
	1239	+
	1240	+ /**
	1241	+ * Is this cached page being served for a URL that no purge names?
	1242	+ *
	1243	+ * Free serves `/post?utm_source=x` from the entry stored for `/post`,
	1244	+ * which is what the ignored-params list is for. An edge does not. It
	1245	+ * keys on the full URL, so every query string becomes its own copy. A
	1246	+ * purge that names `/post` clears one copy and leaves the others for the
	1247	+ * whole edge lifetime. A newsletter link can then serve last month's
	1248	+ * page. So such a HIT is held, and the edge keeps only URLs a purge can
	1249	+ * name. See query_carries_unpurged_param() for which query strings count.
	1250	+ *
	1251	+ * A HIT only. A MISS is already held as `miss`, and a BYPASS never
	1252	+ * reached the cache. And `request` only, because the query string belongs
	1253	+ * to the request, not to the entry. One stored file answers `/post` and
	1254	+ * every variant of it, so a hold written into its sidecar under `store`
	1255	+ * would be replayed by the drop-in for the plain URL as well. A `bake`
	1256	+ * says no unless query_variant_edge_headers() is asking for the drop-in.
	1257	+ *
	1258	+ * @param string $status `HIT`, `MISS` or `BYPASS`.
	1259	+ * @param string $context `request`, `store` or `bake`.
	1260	+ */
	1261	+ private static function serves_query_variant( string $status, string $context ): bool {
	1262	+ if ( 'HIT' !== $status ) {
	1263	+ return false;
	1264	+ }
	1265	+ if ( 'bake' === $context ) {
	1266	+ return self::$baking_query_variant;
	1267	+ }
	1268	+
	1269	+ return 'request' === $context && self::query_carries_unpurged_param();
	1270	+ }
	1271	+
	1272	+ /**
	1273	+ * Does this request's query string carry a param that keeps its URL out
	1274	+ * of every purge?
	1275	+ *
	1276	+ * Two kinds do. A param the cache key leaves out, which is anything on
	1277	+ * the ignored-params list, judged by query_key_is_ignored() against the
	1278	+ * same setting should_cache() reads. And the search and query-form feed
	1279	+ * params (`s`, FEED_QUERY_PARAMS). Those have entries keyed their own
	1280	+ * way, but they belong to opt-in caches whose URLs no purge names either.
	1281	+ *
	1282	+ * Any other param that reaches a HIT is part of the page's own address,
	1283	+ * which a purge names, so it is not held. A plain-permalink route such
	1284	+ * as `/?page_id=2` is the case this leaves alone.
	1285	+ */
	1286	+ private static function query_carries_unpurged_param(): bool {
	1287	+ $query_raw = isset( $_SERVER['QUERY_STRING'] ) ? (string) wp_unslash( $_SERVER['QUERY_STRING'] ) : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- parsed for its keys only, as should_cache() does; never echoed or stored.
	1288	+ if ( '' === trim( $query_raw ) ) {
	1289	+ return false;
	1290	+ }
	1291	+
	1292	+ parse_str( $query_raw, $params );
	1293	+ $cache_opts = Settings_Manager::get( 'cache' );
	1294	+ $ignored = is_array( $cache_opts['ignored_query_params'] ?? null ) ? $cache_opts['ignored_query_params'] : array();
	1295	+ foreach ( array_keys( $params ) as $key ) {
	1296	+ $key = (string) $key;
	1297	+ if ( 's' === $key || in_array( $key, self::FEED_QUERY_PARAMS, true ) ) {
	1298	+ return true;
	1299	+ }
	1300	+ if ( self::query_key_is_ignored( $key, $ignored ) ) {
	1301	+ return true;
	1302	+ }
	1303	+ }
	1304	+
	1305	+ return false;
	1306	+ }
	1307	+
	1308	+ /**
	1309	+ * The edge answer the drop-in sends for a cached page served for a URL
	1310	+ * no purge names, or an empty array when that answer is the same as the
	1311	+ * plain URL's.
	1312	+ *
	1313	+ * The drop-in runs before plugins load and cannot ask edge_headers_for(),
	1314	+ * so this is baked in next to the plain answer. The drop-in applies it
	1315	+ * when a param in the query string matches the ignored-params list it
	1316	+ * already reads (`.ignored-query-params`, written from the same setting
	1317	+ * by sync_query_allowlist()). Search and feed params never reach it,
	1318	+ * because it hands those requests to PHP. The nginx and Apache
	1319	+ * rules need no copy. Both refuse any request with a query string
	1320	+ * (`if ($args)`, `RewriteCond %{QUERY_STRING} ^$`), so a variant always
	1321	+ * reaches PHP.
	1322	+ *
	1323	+ * Empty when the two answers agree. That covers no edge being known,
	1324	+ * a filter vetoing the hold, and a site where every page is held
	1325	+ * already (mobile-split). The drop-in then sends what it sends for the
	1326	+ * plain URL, including any sidecar the page has.
	1327	+ *
	1328	+ * @return array<string,string>
	1329	+ */
	1330	+ public static function query_variant_edge_headers(): array {
	1331	+ $plain = self::edge_headers_for( 'HIT', 'bake' );
	1332	+
	1333	+ self::$baking_query_variant = true;
	1334	+ try {
	1335	+ $variant = self::edge_headers_for( 'HIT', 'bake' );
	1336	+ } finally {
	1337	+ self::$baking_query_variant = false;
	1338	+ }
	1339	+
	1340	+ return $variant === $plain ? array() : $variant;
	1341	+ }
	1342	+
	1343	+ /**
	1344	+ * Why, if at all, a cache in front of us should refuse to store this.
	1345	+ *
	1346	+ * @param string $status `HIT`, `MISS` or `BYPASS`.
	1347	+ * @param string $context `request`, `store` or `bake`.
	1348	+ * @param string $bypass_reason The gate slug, for BYPASS only.
	1349	+ * @return string '' or one of bypass|bypass-shape|miss|mobile-split|pending|query-variant.
	1350	+ */
	1351	+ private static function edge_hold_reason( string $status, string $context, string $bypass_reason ): string {
	1352	+ $reason = '';
	1353	+
	1354	+ // The two exempt gates are answered before anything else, or a site
	1355	+ // with Separate Mobile Cache on would keep holding after the page
	1356	+ // cache was switched off — which is exactly the "a local toggle must
	1357	+ // not become a site-wide side effect on infrastructure we do not own"
	1358	+ // rule below, defeated by the ordering rather than by the logic.
	1359	+ if ( 'BYPASS' === $status && in_array( $bypass_reason, self::HOLD_EXEMPT_BYPASS, true ) ) {
	1360	+ /** This filter is documented below. */
	1361	+ return (string) apply_filters( 'xspeed_edge_hold_reason', '', $status, $context, $bypass_reason );
	1362	+ }
	1363	+
	1364	+ // First, because it is the only reason true in every context: the
	1365	+ // setting is a property of the site, not of one request, so it is the
	1366	+ // one thing a baked artifact can honestly assert.
	1367	+ //
	1368	+ // It is also the only reason that holds a HIT — a response we DID
	1369	+ // cache — and that is deliberate rather than an artefact of the
	1370	+ // ordering. With mobile_separate on we key the cache by device and
	1371	+ // serve different HTML to a phone than to a desktop at the same URL.
	1372	+ // No CDN varies on User-Agent, so an edge holding one of those
	1373	+ // renders serves it to everyone and whichever device asked first
	1374	+ // decides what the other sees. Our copy is fine; theirs would be a
	1375	+ // wrong page. The static path is switched off in this mode anyway
	1376	+ // (static_rewrite_allowed()), so these hits come from the drop-in,
	1377	+ // which carries the same baked answer.
	1378	+ if ( self::mobile_cache_splits_html() ) {
	1379	+ $reason = 'mobile-split';
	1380	+ } elseif ( 'BYPASS' === $status ) {
	1381	+ $shaped = in_array( $bypass_reason, array( 'excluded-url', 'query-param' ), true )
	1382	+ ? ! self::path_is_a_personal_exclusion( $bypass_reason )
	1383	+ : in_array( $bypass_reason, self::REQUEST_SHAPE_BYPASS, true );
	1384	+ $reason = $shaped ? 'bypass-shape' : 'bypass';
	1385	+ } elseif ( self::edge_optimization_pending( $context ) ) {
	1386	+ $reason = 'pending';
	1387	+ } elseif ( 'MISS' === $status ) {
	1388	+ $reason = 'miss';
	1389	+ } elseif ( self::serves_query_variant( $status, $context ) ) {
	1390	+ // Last, so it only adds a hold where there was none. A variant
	1391	+ // still waiting for its CSS says `pending`, which is also true,
	1392	+ // and the CSS modules are still asked on every HIT as before.
	1393	+ $reason = 'query-variant';
	1394	+ }
	1395	+
	1396	+ /**
	1397	+ * Filter: xspeed_edge_hold_reason
	1398	+ *
	1399	+ * Return '' to veto a hold, or a reason string to force one.
	1400	+ *
	1401	+ * @param string $reason '' or bypass|bypass-shape|miss|mobile-split|pending|query-variant.
	1402	+ * @param string $status `HIT`, `MISS` or `BYPASS`.
	1403	+ * @param string $context `request`, `store` or `bake`.
	1404	+ * @param string $bypass_reason The gate slug, for BYPASS only.
	1405	+ */
	1406	+ return (string) apply_filters( 'xspeed_edge_hold_reason', $reason, $status, $context, $bypass_reason );
	1407	+ }
	1408	+
	1409	+ /**
	1410	+ * Was this page excluded because it is personal, or because it is
	1411	+ * plumbing we cannot key a cache entry on?
	1412	+ *
	1413	+ * Answers by removing the structural defaults from the site's own
	1414	+ * exclusion list and asking whether anything is left that matches. So a
	1415	+ * feed matches only `/feed/` and comes back false; `/my-account/feedback/`
	1416	+ * matches `/my-account` and comes back true; and on an "almost pretty"
	1417	+ * permalink site, where every path contains `index.php`, an ordinary page
	1418	+ * matches nothing else and is correctly treated as public.
	1419	+ *
	1420	+ * The path only, never the query string — a visitor writes that, and
	1421	+ * `/cart/?utm_source=/feed/` must not be able to talk a cart out of its
	1422	+ * hold. It is also what `should_cache()` matches the list against.
	1423	+ *
	1424	+ * Asked for a `query-param` bypass too, because the query gate runs
	1425	+ * BEFORE the URL gate, so `/cart/?add-to-cart=12` reports `query-param`
	1426	+ * and never reaches `excluded-url` at all. Which gate fired first says
	1427	+ * nothing about whose data is on the page.
	1428	+ */
	1429	+ private static function path_is_a_personal_exclusion( string $bypass_reason ): bool {
	1430	+ $path = self::request_path();
	1431	+ if ( '' === $path ) {
	1432	+ return false;
	1433	+ }
	1434	+
	1435	+ // Through Settings_Manager, not the raw option, because the schema's
	1436	+ // default IS the structural list and a fresh install has never
	1437	+ // written the option. Read raw, every site that has not visited the
	1438	+ // settings screen looks like a site with no exclusions at all, takes
	1439	+ // the contradiction branch below, and reports its feeds as personal.
	1440	+ //
	1441	+ // Safe here where `mobile_cache_splits_html()` is not: we are only
	1442	+ // ever called with a bypass reason, and those come from
	1443	+ // `should_cache()`, which resolved the same settings through
	1444	+ // `Settings_Manager::get()` to produce them.
	1445	+ $opts = Settings_Manager::get( 'cache' );
	1446	+ $excluded = is_array( $opts['excluded_urls'] ?? null ) ? $opts['excluded_urls'] : array();
	1447	+ if ( array() === $excluded ) {
	1448	+ // An `excluded-url` bypass with no exclusion list is a
	1449	+ // contradiction — something excluded the request and the list
	1450	+ // cannot say what — so assume personal, because a wasted header
	1451	+ // costs a little origin traffic while a missing one serves
	1452	+ // somebody's basket to a stranger. A `query-param` bypass with an
	1453	+ // empty list is just an ordinary page carrying a parameter, and
	1454	+ // says nothing about the path at all.
	1455	+ return 'excluded-url' === $bypass_reason;
	1456	+ }
	1457	+
	1458	+ $personal = array_values(
	1459	+ array_filter(
	1460	+ $excluded,
	1461	+ static fn ( $pattern ) => ! in_array( (string) $pattern, self::STRUCTURAL_EXCLUSIONS, true )
	1462	+ )
	1463	+ );
	1464	+
	1465	+ return array() !== $personal && self::path_matches_exclusions( $personal, $path );
	1466	+ }
	1467	+
	1468	+ /**
	1469	+ * The edge/CDN headers to send on a response with this cache status.
	1470	+ *
	1471	+ * @param string $status `HIT`, `MISS` or `BYPASS`.
	1472	+ * @param string $context `request` when resolved per request on the
	1473	+ * PHP serve path, `store` when resolved for
	1474	+ * one entry's sidecar, `bake` when resolved
	1475	+ * once and frozen into the drop-in, `rules`
	1476	+ * when resolved once for the nginx or Apache
	1477	+ * static block.
	1478	+ * @param string $bypass_reason The gate slug, for BYPASS only.
	1479	+ * @return array<string,string>
	1480	+ */
	1481	+ public static function edge_headers_for( string $status, string $context = 'request', string $bypass_reason = '' ): array {
	1482	+ // `rules` is a bake in every respect but one: the cache-headers
	1483	+ // filter is told it is answering for a pasted server rule. Such a
	1484	+ // rule serves every static HIT for as long as it stays pasted, and
	1485	+ // nothing regenerates it when the site's expiry or a page's own
	1486	+ // lifetime (a nonce cap) changes, so a lifetime given there cannot
	1487	+ // follow the page. The drop-in is rewritten by auto_heal(); a paste
	1488	+ // is not.
	1489	+ $filter_context = $context;
	1490	+ if ( 'rules' === $context ) {
	1491	+ $context = 'bake';
	1492	+ }
	1493	+
	1494	+ $base = array();
	1495	+ if ( 'HIT' === $status ) {
	1496	+ /**
	1497	+ * Filter: xspeed_edge_cache_headers
	1498	+ *
	1499	+ * Response headers to add to a cached HTML response. The lifetime
	1500	+ * is HIT-only: it is a promise that this copy is worth keeping,
	1501	+ * and neither a first render nor a page we refused to cache is
	1502	+ * one. The filter is also asked with `MISS` when a first render
	1503	+ * is held, and only the `Cache-Tag` from that answer is sent, so
	1504	+ * a purge can name a copy an edge stored despite the hold.
	1505	+ *
	1506	+ * The same filter feeds four regimes and `$context` says which.
	1507	+ * On the PHP serve path it runs per request (`request`); at store
	1508	+ * time it runs for one entry (`store`); when the drop-in is
	1509	+ * generated it runs once (`bake`) and the result answers for
	1510	+ * every drop-in HIT on the site; when the nginx or Apache static
	1511	+ * block is generated it runs once (`rules`). Anything per-page — a
	1512	+ * post id in a cache tag, say — must be skipped under `bake` and
	1513	+ * `rules`. A server rule serves every static HIT for as long as it
	1514	+ * stays pasted, so a lifetime here can't follow the page: send
	1515	+ * none under `rules`.
	1516	+ *
	1517	+ * @param array<string,string> $headers Header name => value.
	1518	+ * @param string $status `HIT`, or `MISS` when only the tag of a held first render is wanted.
	1519	+ * @param string $context `request`, `store`, `bake` or `rules`.
	1520	+ */
	1521	+ $base = self::sanitize_edge_headers( (array) apply_filters( 'xspeed_edge_cache_headers', array(), 'HIT', $filter_context ) );
	1522	+ }
	1523	+
	1524	+ $reason = self::edge_hold_reason( $status, $context, $bypass_reason );
	1525	+ if ( '' === $reason ) {
	1526	+ return $base;
	1527	+ }
	1528	+ $detected = Edge_Provider::detect( $context );
	1529	+ if ( Edge_Provider::is_off( $detected ) ) {
	1530	+ return $base;
	1531	+ }
	1532	+ if ( Edge_Provider::NONE === $detected['confidence']
	1533	+ && ! in_array( $reason, self::HOLD_WITHOUT_EVIDENCE, true ) ) {
	1534	+ return $base;
	1535	+ }
	1536	+
	1537	+ $hold = Edge_Provider::hold_headers( $detected['provider'] );
	1538	+
	1539	+ /**
	1540	+ * Filter: xspeed_edge_hold_headers
	1541	+ *
	1542	+ * The last word on what a hold INSTRUCTS. Runs before sanitising, so
	1543	+ * a value that cannot be sent as a header is still dropped, and
	1544	+ * before `X-XSpeed-Edge-Hold` is added, so it cannot rewrite the
	1545	+ * reason xSpeed held the page for — that is a diagnosis, not an
	1546	+ * instruction, and a forged one sends a reader after the wrong
	1547	+ * module.
	1548	+ *
	1549	+ * @param array<string,string> $hold Header name => value.
	1550	+ * @param array<string,string> $detected Provider, confidence, source.
	1551	+ * @param string $reason Why the hold fired.
	1552	+ * @param string $context `request`, `store` or `bake`.
	1553	+ */
	1554	+ $hold = (array) apply_filters( 'xspeed_edge_hold_headers', $hold, $detected, $reason, $context );
	1555	+
	1556	+ // A hold replaces the lifetime rather than sitting beside it: the two
	1557	+ // describe the same response and would contradict each other. The
	1558	+ // cache tag survives, because a later purge still has to be able to
	1559	+ // name whatever the edge picked up on its own terms.
	1560	+ //
	1561	+ // On a HIT the tag came with `$base`. A MISS has no `$base`, and that
	1562	+ // is the case that mattered most: the first render after any purge.
	1563	+ // An edge whose rule overrides the origin's lifetime stores it
	1564	+ // despite the hold, and with no tag on it the next tag purge cannot
	1565	+ // reach it, so an edit stayed stale for the edge's whole lifetime
	1566	+ // (QA, 2026-09-23). So a held MISS asks the same filter for its tag
	1567	+ // and keeps the tag alone; the lifetime in the answer is dropped,
	1568	+ // because the hold is the instruction for this response.
	1569	+ $tag = $base['Cache-Tag'] ?? '';
	1570	+ if ( '' === $tag && 'MISS' === $status ) {
	1571	+ $tagged = self::sanitize_edge_headers( (array) apply_filters( 'xspeed_edge_cache_headers', array(), 'MISS', $filter_context ) );
	1572	+ $tag = $tagged['Cache-Tag'] ?? '';
	1573	+ }
	1574	+ if ( '' !== $tag ) {
	1575	+ $hold['Cache-Tag'] = $tag;
	1576	+ }
	1577	+
	1578	+ // Never argue with a stronger answer WordPress already gave. It sends
	1579	+ // `no-store, private` of its own accord on a logged-in, 404 or
	1580	+ // password-protected response, from WP::send_headers() — which runs
	1581	+ // before template_redirect, so it is already on the wire by the time
	1582	+ // we get here. Ours is the weaker statement of the two; replacing it
	1583	+ // would be a downgrade dressed as a fix. Only meaningful per request:
	1584	+ // a bake has no response to inspect.
	1585	+ if ( 'request' === $context && isset( $hold['Cache-Control'] ) && self::cache_control_already_stronger() ) {
	1586	+ unset( $hold['Cache-Control'] );
	1587	+ }
	1588	+
	1589	+ // A page we refused to cache must not carry a validator either. A
	1590	+ // `Last-Modified` left on it invites a conditional request, and a
	1591	+ // shared cache that gets a 304 back serves the copy it should not
	1592	+ // have stored. Only on a bypass, and only per request: a MISS is
	1593	+ // about to be stored by us, so its validator is ours to keep.
	1594	+ if ( 'request' === $context && 'bypass' === $reason && ! headers_sent() ) {
	1595	+ header_remove( 'Last-Modified' );
	1596	+ }
	1597	+
	1598	+ $hold = self::sanitize_edge_headers( $hold );
	1599	+
	1600	+ // Name the reason in the hold set itself, rather than sending it
	1601	+ // separately from mark().
	1602	+ //
	1603	+ // "Why is my page not being cached at the edge?" is the question this
	1604	+ // answers, and mark() could only answer it on the PHP serve path. The
	1605	+ // other emitters send whatever this function returns and never ran
	1606	+ // mark() at all — so the responses hardest to explain went out
	1607	+ // carrying `no-store` with nothing beside it to say why. Chiefly the
	1608	+ // drop-in, which serves from the `.meta` sidecar written under
	1609	+ // `store` and from the literal baked under `bake`, before plugins
	1610	+ // load and with no way to re-ask (the symptom
	1611	+ // edge_optimization_pending() describes above).
	1612	+ //
	1613	+ // The nginx and Apache blocks are a third path in principle and
	1614	+ // almost never in practice: they are only installed when
	1615	+ // static_rewrite_allowed() is true, and the one reason a stock site
	1616	+ // can hold in their bake is `mobile-split`, which is exactly what
	1617	+ // makes that false. `query-variant` is baked for the drop-in alone,
	1618	+ // since both blocks refuse a query string. They will carry a hold
	1619	+ // where a site forces one through `xspeed_edge_hold_reason`, and
	1620	+ // otherwise have none to carry.
	1621	+ //
	1622	+ // Added AFTER sanitising and banned in NEVER_AN_EDGE_HEADER, so
	1623	+ // neither of the two filters above can forge a reason or suppress the
	1624	+ // real one.
	1625	+ //
	1626	+ // Reduced to the slug CHARACTER CLASS, not checked against the six
	1627	+ // slugs: `xspeed_edge_hold_reason` is documented as able to force a
	1628	+ // reason, and a site that forces its own deserves to see it. What is
	1629	+ // not negotiable is the shape, because this value reaches an
	1630	+ // .htaccess and an nginx conf as well as a response header — so no
	1631	+ // CR/LF, no `$`, no `%`, no `\`, and a length a config file can hold.
	1632	+ $slug = preg_replace( '/[^a-z0-9-]/', '', strtolower( $reason ) );
	1633	+ if ( is_string( $slug ) && '' !== $slug ) {
	1634	+ $hold['X-XSpeed-Edge-Hold'] = substr( $slug, 0, 32 );
	1635	+ }
	1636	+
	1637	+ return $hold;
	1638	+ }
	1639	+
	1640	+ /** Has something already sent a Cache-Control at least as strict as ours? */
	1641	+ private static function cache_control_already_stronger(): bool {
	1642	+ foreach ( headers_list() as $line ) {
	1643	+ if ( 0 !== stripos( $line, 'cache-control:' ) ) {
	1644	+ continue;
	1645	+ }
	1646	+ if ( preg_match( '/\b(?:no-store|private)\b/i', $line ) ) {
	1647	+ return true;
	1648	+ }
	1649	+ }
	1650	+
	1651	+ return false;
	1652	+ }
	1653	+
	1654	+ /**
	1655	+ * Edge headers that belong to THIS page rather than to every page.
	1656	+ *
	1657	+ * `edge_headers_for('HIT','bake')` is the answer frozen into the drop-in
	1658	+ * and the server rules: one set, serving the whole site. But the answer
	1659	+ * for one URL can legitimately differ — a page whose deferred work is
	1660	+ * still outstanding, say — and that answer has nowhere to live, because
	1661	+ * the baked set is all the fast paths know about.
	1662	+ *
	1663	+ * So ask again in a `store` context, with the request still in scope, and
	1664	+ * return the pairs only when they differ from the baked ones. Identical is
	1665	+ * the overwhelmingly common case and writes nothing: pages do not pay a
	1666	+ * sidecar for an answer the drop-in already has.
	1667	+ *
	1668	+ * Memoised because two callers ask within one store — the sidecar writer
	1669	+ * and the static-tree guard — and the filters behind it are not required
	1670	+ * to be cheap.
	1671	+ *
	1672	+ * A page with a lifetime of its own also gets its own pairs, whenever
	1673	+ * they grant an edge any lifetime at all. The lifetime is cut to the
	1674	+ * page's (see cap_edge_lifetime()), and the pairs are returned even when
	1675	+ * the cut leaves them equal to the baked ones. Returning them keeps the
	1676	+ * page off the static tree, and it has to: only the two PHP paths can
	1677	+ * count a lifetime down as the copy ages. The web server sends the baked
	1678	+ * value from whatever age the file has reached, so a page capped to its
	1679	+ * nonce would reach the edge with hours of dead nonce still to serve.
	1680	+ *
	1681	+ * write_meta() resolves that lifetime and passes it on the first call.
	1682	+ * The static-tree guards ask afterwards and read the memo. Both store
	1683	+ * paths call write_meta() before their guard.
	1684	+ *
	1685	+ * @param int|null $own_ttl The entry's own lifetime in seconds, when it
	1686	+ * differs from the site's (the sidecar `ttl`).
	1687	+ * @return array<string,string> Empty when this page needs no override.
	1688	+ */
	1689	+ private static function per_entry_edge_headers( ?int $own_ttl = null ): array {
	1690	+ if ( is_array( self::$per_entry_edge ) ) {
	1691	+ return self::$per_entry_edge;
	1692	+ }
	1693	+ $baked = self::edge_headers_for( 'HIT', 'bake' );
	1694	+ $request = self::edge_headers_for( 'HIT', 'store' );
	1695	+ if ( null !== $own_ttl && self::grants_edge_lifetime( $request ) ) {
	1696	+ self::$per_entry_edge = self::cap_edge_lifetime( $request, $own_ttl );
	1697	+ return self::$per_entry_edge;
	1698	+ }
	1699	+ self::$per_entry_edge = ( $request === $baked ) ? array() : $request;
	1700	+
	1701	+ return self::$per_entry_edge;
	1702	+ }
	1703	+
	1704	+ /**
	1705	+ * Cut every lifetime an edge header grants down to `$seconds`.
	1706	+ *
	1707	+ * The lifetime in a HIT's pairs comes from `xspeed_edge_cache_headers`
	1708	+ * and describes the site, so it says nothing of a page whose own lifetime
	1709	+ * is shorter: one carrying a nonce (#236), one with a per-post expiry,
	1710	+ * one a `xspeed_cache_max_age` filter shortened. xSpeed rebuilds that page
	1711	+ * on time, and an edge holding it for the site's lifetime goes on serving
	1712	+ * the old copy anyway. Nothing tells the edge when our copy expires,
	1713	+ * because an expiry is not a purge. For a nonce page that is a broken
	1714	+ * form for every visitor until the next purge.
	1715	+ *
	1716	+ * Only shortens. A `max-age` or `s-maxage` already under `$seconds` is
	1717	+ * kept, so a hold's `s-maxage=0` stays 0. Only headers named `*-Control`
	1718	+ * are touched; a `Cache-Tag` that happens to contain the text is not a
	1719	+ * directive.
	1720	+ *
	1721	+ * @param array<string,string> $headers Header name => value.
	1722	+ * @param int $seconds The most any of them may grant.
	1723	+ * @return array<string,string>
	1724	+ */
	1725	+ public static function cap_edge_lifetime( array $headers, int $seconds ): array {
	1726	+ $seconds = max( 0, $seconds );
	1727	+ foreach ( $headers as $name => $value ) {
	1728	+ if ( ! preg_match( self::EDGE_LIFETIME_HEADER, (string) $name ) ) {
	1729	+ continue;
	1730	+ }
	1731	+ $capped = preg_replace_callback(
	1732	+ self::EDGE_LIFETIME_DIRECTIVE,
	1733	+ static function ( array $m ) use ( $seconds ): string {
	1734	+ return $m[1] . '=' . min( (int) $m[2], $seconds );
	1735	+ },
	1736	+ (string) $value
	1737	+ );
	1738	+ if ( is_string( $capped ) ) {
	1739	+ $headers[ $name ] = $capped;
	1740	+ }
	1741	+ }
	1742	+
	1743	+ return $headers;
	1744	+ }
	1745	+
	1746	+ /**
	1747	+ * Does any `*-Control` header in the set let an edge keep the response?
	1748	+ *
	1749	+ * @param array<string,string> $headers Header name => value.
	1750	+ */
	1751	+ private static function grants_edge_lifetime( array $headers ): bool {
	1752	+ foreach ( $headers as $name => $value ) {
	1753	+ if ( ! preg_match( self::EDGE_LIFETIME_HEADER, (string) $name ) ) {
	1754	+ continue;
	1755	+ }
	1756	+ if ( preg_match_all( self::EDGE_LIFETIME_DIRECTIVE, (string) $value, $m ) ) {
	1757	+ foreach ( $m[2] as $seconds ) {
	1758	+ if ( (int) $seconds > 0 ) {
	1759	+ return true;
	1760	+ }
	1761	+ }
	1762	+ }
	1763	+ }
	1764	+
	1765	+ return false;
	1766	+ }
	1767	+
	1768	+ /**
	1769	+ * Seconds a cached entry has left, when it has a lifetime of its own.
	1770	+ *
	1771	+ * Read from the sidecar `ttl`, which write_meta() records only when the
	1772	+ * entry's lifetime differs from the site's. That is the drop-in's rule
	1773	+ * too, so both PHP serve paths count down the same entries. Null for an
	1774	+ * entry that follows the site's lifetime: what the edge is told about
	1775	+ * those is the site's lifetime, unchanged.
	1776	+ *
	1777	+ * @param array<string,mixed> $meta The entry's sidecar, from read_meta().
	1778	+ * @param string $file The cached file being served.
	1779	+ */
	1780	+ private static function entry_lifetime_left( array $meta, string $file ): ?int {
	1781	+ $ttl = isset( $meta['ttl'] ) ? (int) $meta['ttl'] : 0;
	1782	+ if ( $ttl < 1 ) {
	1783	+ return null;
	1784	+ }
	1785	+ $mtime = file_exists( $file ) ? filemtime( $file ) : false;
	1786	+ if ( false === $mtime ) {
	1787	+ return null;
	1788	+ }
	1789	+
	1790	+ return max( 0, $ttl - ( time() - (int) $mtime ) );
	1791	+ }
	1792	+
	1793	+ /**
	1794	+ * Render baked pairs as a PHP array literal for the drop-in.
	1795	+ *
	1796	+ * Single-quoted literals with quotes escaped, because the result is
	1797	+ * written into a PHP file that must still parse. Values reaching here
	1798	+ * have already been through sanitize_edge_headers(), so neither name nor
	1799	+ * value can carry a newline.
	1800	+ *
	1801	+ * @param array<string,string> $headers Name => value.
	1802	+ */
	1803	+ private static function edge_headers_literal( array $headers ): string {
	1804	+ if ( array() === $headers ) {
	1805	+ return 'array()';
	1806	+ }
	1807	+ // var_export(), not hand-rolled quoting. A single-quoted PHP string
	1808	+ // escapes BOTH `'` and `\\`, and escaping only the first is how a
	1809	+ // value ending in a backslash — `X-Foo: C:\path\` from the custom
	1810	+ // headers box — leaves the literal unterminated. That file is
	1811	+ // included on every request once WP_CACHE is on, so the result is a
	1812	+ // parse error on the front end AND in wp-admin, with no way back
	1813	+ // except deleting the file over SSH.
	1814	+ $parts = array();
	1815	+ foreach ( $headers as $name => $value ) {
	1816	+ $parts[] = var_export( (string) $name, true ) . ' => ' . var_export( (string) $value, true );
	1817	+ }
	1818	+
	1819	+ return 'array( ' . implode( ', ', $parts ) . ' )';
	1820	+ }
	1821	+
	1822	+ /**
	1823	+ * Quote a header value for an nginx / Apache directive.
	1824	+ *
	1825	+ * Both accept a double-quoted string with backslash escapes, and both
	1826	+ * refuse to load a config where the quoting is wrong — a mis-escaped
	1827	+ * value takes the whole vhost down, not just this header.
	1828	+ */
	1829	+ private static function quote_directive_value( string $value ): string {
	1830	+ return str_replace( array( '\\', '"' ), array( '\\\\', '\\"' ), $value );
	1831	+ }
	1832	+
	1833	+ /**
	1834	+ * The same directive twice — once per name Apache can expose the
	1835	+ * rewrite's environment variable under.
	1836	+ *
	1837	+ * `RewriteRule ... [E=XSPEED_STATIC_HIT:1]` in a per-directory context is
	1838	+ * an INTERNAL REDIRECT: Apache re-enters the request with the substituted
	1839	+ * path, and every variable set on the first pass is renamed with a
	1840	+ * `REDIRECT_` prefix for the second. `env=XSPEED_STATIC_HIT` is evaluated
	1841	+ * on that second pass, where nothing answers to that name any more, so
	1842	+ * the directive never fires — dropping the headers from precisely the
	1843	+ * responses they exist for. The rules marker rides on the same gate, so
	1844	+ * the probe also read its own marker as missing and called correctly
	1845	+ * installed rules stale.
	1846	+ *
	1847	+ * It cannot be written once: `env=` takes a single name with no
	1848	+ * alternation, and `expr=` — which could express both — is not dependable
	1849	+ * on LiteSpeed, which reads this same block. So both are emitted; the one
	1850	+ * whose variable is unset on a given pass does nothing.
	1851	+ *
	1852	+ * @param string $directive The directive, without its `env=` clause.
	1853	+ * @return string[]
	1854	+ */
	1855	+ private static function static_hit_directives( string $directive ): array {
	1856	+ return array(
	1857	+ $directive . ' env=XSPEED_STATIC_HIT',
	1858	+ $directive . ' env=REDIRECT_XSPEED_STATIC_HIT',
	1859	+ );
	1860	+ }
	1861	+
	1862	+ /**
	1863	+ * Keep only pairs that can be sent as a header verbatim.
	1864	+ *
	1865	+ * These values reach three different emitters — PHP's header(), an nginx
	1866	+ * `add_header` and an Apache `Header always set` — so a name with a space
	1867	+ * or a value carrying CR/LF is not merely malformed, it is a
	1868	+ * response-splitting vector in the first and a broken server config in
	1869	+ * the other two. Names must be token-shaped; values lose CR/LF and are
	1870	+ * dropped if nothing survives.
	1871	+ *
	1872	+ * @param array<mixed,mixed> $headers Raw pairs.
	1873	+ * @return array<string,string>
	1874	+ */
	1875	+ public static function sanitize_edge_headers( array $headers ): array {
	1876	+ $clean = array();
	1877	+ foreach ( $headers as $name => $value ) {
	1878	+ // Never let one of these through, whoever asked. They describe the
	1879	+ // transfer rather than the caching policy, and getting one wrong
	1880	+ // from a settings field is a white screen: `Content-Encoding: gzip`
	1881	+ // on an uncompressed body, a `Content-Length` that disagrees with
	1882	+ // the bytes. `X-XSpeed-Cache` is ours and a second copy would lie
	1883	+ // to whoever reads it.
	1884	+ if ( is_string( $name ) && in_array( strtolower( $name ), self::NEVER_AN_EDGE_HEADER, true ) ) {
	1885	+ continue;
	1886	+ }
	1887	+ // `\z`, not `$`: PCRE's `$` also matches immediately BEFORE a
	1888	+ // trailing newline, so "Cache-Tag\n" passes a `$` check and gets
	1889	+ // concatenated raw into the generated .htaccess — splitting one
	1890	+ // Header directive across two lines, which is a syntax error
	1891	+ // Apache reports as a 500 on every request while `httpd -t` stays
	1892	+ // green (.htaccess is parsed per request, not at load).
	1893	+ if ( ! is_string( $name ) || ! preg_match( '/^[A-Za-z0-9-]+\z/', $name ) ) {
	1894	+ continue;
	1895	+ }
	1896	+ if ( ! is_string( $value ) && ! is_numeric( $value ) ) {
	1897	+ continue;
	1898	+ }
	1899	+ $value = trim( str_replace( array( "\r", "\n" ), '', (string) $value ) );
	1900	+ if ( '' === $value ) {
	1901	+ continue;
	1902	+ }
	1903	+ // `$` is a variable reference in an nginx string and `%` is a
	1904	+ // format tag to Apache's mod_headers, which rejects an
	1905	+ // unrecognised one — in .htaccess that is a 500 on every request
	1906	+ // while `httpd -t` still reports OK, because .htaccess is parsed
	1907	+ // per request. `\` escapes the quote in the PHP literal baked into
	1908	+ // the drop-in. None of them can be escaped reliably in all three
	1909	+ // places at once, and nothing a cache reads needs any of them, so
	1910	+ // the value is dropped rather than mangled.
	1911	+ if ( preg_match( '/[$%\\\\]/', $value ) ) {
	1912	+ continue;
	1913	+ }
	1914	+ $clean[ $name ] = $value;
	1915	+ }
	1916	+
	1917	+ return $clean;
	1918	+ }
	1919	+
	1920	+ /**
	1921	+ * Bypass gates that describe THE VISITOR rather than THIS REQUEST.
	1922	+ *
	1923	+ * Only these may be recorded in the bypass cookie. A visitor-scoped
	1924	+ * verdict stays true for the visitor's next request — they are still
	1925	+ * logged in, still hold a cart cookie — so the web server can act on
	1926	+ * it without booting PHP.
	1927	+ *
	1928	+ * Every other gate describes the request in front of us: its method,
	1929	+ * its URL, its query string, the client's user agent. Persisting one
	1930	+ * of those pins a visitor to the uncached path over a property that
	1931	+ * was never theirs to begin with. (#218)
	1932	+ */
	1933	+ private const VISITOR_SCOPED_BYPASS = array( 'logged-in', 'excluded-cookie' );
	1934	+
	1935	+ /**
	1936	+ * Whether $reason describes the visitor (persist it) or merely this
	1937	+ * request (don't).
	1938	+ *
	1939	+ * Split out as a pure function because it is the whole decision behind
	1940	+ * the bypass cookie, and the cookie write itself (setcookie()) can't be
	1941	+ * asserted in a unit test.
	1942	+ */
	1943	+ public static function bypass_is_visitor_scoped( string $reason ): bool {
	1944	+ return in_array( $reason, self::VISITOR_SCOPED_BYPASS, true );
	1945	+ }
	1946	+
65	1947	public function maybe_start_cache() {
66	1948	if ( ! self::should_cache() ) {
	1949	+ // PHP has just evaluated the FULL exclusion rule list — including
	1950	+ // the `~regex` patterns the server config can't express — and
	1951	+ // decided this response must not be served from cache. Record that
	1952	+ // verdict in the conventional bypass cookie so the web server can
	1953	+ // enforce it on subsequent requests without starting PHP.
	1954	+ //
	1955	+ // This is what stops most settings changes from needing an nginx
	1956	+ // reload: the config tests one fixed cookie name forever, and the
	1957	+ // rule list behind it can change freely.
	1958	+ //
	1959	+ // But ONLY when the verdict is about the visitor. A request-shape
	1960	+ // gate — `non-get` above all — says nothing about who is asking,
	1961	+ // and persisting it pinned that visitor to the uncached path for
	1962	+ // the rest of their session: one search-form POST, one comment,
	1963	+ // one `curl -I` from an uptime monitor, and every later GET
	1964	+ // bypassed. It could not self-heal either, because the bypass
	1965	+ // cookie is itself in excluded_cookies, so the next GET bypassed
	1966	+ // with `excluded-cookie` and landed right back here, where
	1967	+ // sync_bypass_cookie()'s no-change short-circuit left the cookie
	1968	+ // exactly where it was. (#218)
	1969	+ if ( self::bypass_is_visitor_scoped( self::bypass_reason() ) ) {
	1970	+ self::sync_bypass_cookie( true );
	1971	+ }
67	1972	return;
68	1973	}
69	1974
	1975	+ // Cacheable: clear any stale bypass cookie, or a visitor who once
	1976	+ // had a cart would keep skipping the fast path long after checkout.
	1977	+ self::sync_bypass_cookie( false );
	1978	+
70	1979	$key = self::cache_key();
71	1980	$file = self::cache_file_for( $key );
72	1981
73	1982	if ( file_exists( $file ) && ! self::is_expired( $file ) ) {
74		- Hit_Counter::record_hit();
	1983	+ // Symmetric with the miss branch below: a bot, scanner or one of
	1984	+ // xSpeed's own warm/benchmark requests that lands a HIT must not
	1985	+ // inflate the ratio either — excluding only their misses would
	1986	+ // shrink the denominator while their hits kept feeding the
	1987	+ // numerator, making the displayed ratio MORE optimistic than
	1988	+ // before the exclusion existed.
	1989	+ if ( self::miss_is_excluded() ) {
	1990	+ Hit_Counter::record_excluded();
	1991	+ } else {
	1992	+ Hit_Counter::record_hit();
	1993	+ }
75	1994	// Emit the HIT marker on THIS path too. The drop-in
76	1995	// (advanced-cache.php) sends "HIT (php)" and the nginx static
77	1996	// rewrite sends "HIT (nginx)", but this template_redirect
78	1997	// serve path — the one that runs when the drop-in isn't loaded
		@@ -78,16 +1997,18 @@
78	1997	// serve path — the one that runs when the drop-in isn't loaded
79	1998	// (e.g. WP_CACHE not true) — previously streamed the cached
80	1999	// file with NO marker, so a genuine HIT looked like a MISS in
81	2000	// the response headers. Same header + value as the drop-in.
82		- if ( ! headers_sent() ) {
83		- header( 'X-XSpeed-Cache: HIT (php)' );
84		- }
	2001	+ //
	2002	+ // The sidecar is read first because the HIT's edge lifetime
	2003	+ // depends on it: an entry with a lifetime of its own may not be
	2004	+ // kept at the edge past it. See entry_lifetime_left().
	2005	+ $meta = self::read_meta( $key );
	2006	+ self::mark( 'HIT (php)', '', self::entry_lifetime_left( $meta, $file ) );
85	2007	// Replay stored response bits so the HIT matches the original:
86	2008	// a non-HTML Content-Type (cached feeds, sitemaps) and a non-200
87	2009	// status (a cached 404 must serve 404, not 200). No-op for
88	2010	// ordinary pages, which write no .meta.
89		- $meta = self::read_meta( $key );
90	2011	if ( ! headers_sent() ) {
91	2012	if ( ! empty( $meta['status'] ) && function_exists( 'http_response_code' ) ) {
92	2013	http_response_code( (int) $meta['status'] );
93	2014	}
		@@ -126,16 +2047,33 @@
126	2047	// Apache. See maybe_emit_lscache_headers() for the full rationale.
127	2048	self::maybe_emit_lscache_headers();
128	2049
129	2050	// We're about to render fresh + cache → miss for this request.
130		- Hit_Counter::record_miss();
	2051	+ // …UNLESS this request is a 404 or a known bot/scanner. Those reach the
	2052	+ // render path too, but counting them as cache misses makes the ratio
	2053	+ // meaningless — a wave of `/wp-x7.php` scanner 404s reads as a collapsing
	2054	+ // cache when nothing is wrong. Runs at template_redirect (priority 0), so
	2055	+ // is_404() is already resolved. Excluded requests are tallied separately
	2056	+ // for the "you absorbed N scanner hits" line, not dropped. (#118)
	2057	+ if ( self::miss_is_excluded() ) {
	2058	+ Hit_Counter::record_excluded();
	2059	+ } else {
	2060	+ Hit_Counter::record_miss();
	2061	+ }
131	2062
	2063	+ // Stamp it, so "eligible but not cached yet" is visibly different
	2064	+ // from "deliberately bypassed" (issue #10). Headers can't be sent
	2065	+ // after the body starts, so this has to happen here, not in
	2066	+ // finalize_buffer() — nothing has been output at template_redirect.
	2067	+ self::mark( 'MISS' );
132	2068
	2069	+
133	2070	// WP < 6.9 fallback: ob_start() with a callback, paired with an
134	2071	// explicit shutdown close so the buffer lifecycle is visible to
135	2072	// reviewers and Plugin Check, instead of relying on PHP's implicit
136	2073	// request-end flush. We record our nesting level so close_buffer()
137	2074	// flushes ONLY the buffer we opened.
	2075	+ self::$asset_stamp_at_open = class_exists( '\\XSpeed\\Minifier' ) ? Minifier::purge_stamp() : null;
138	2076	ob_start( array( __CLASS__, 'finalize_buffer' ) );
139	2077	self::$buffer_level = ob_get_level();
140	2078
141	2079	add_action( 'shutdown', array( __CLASS__, 'close_buffer' ), 0 );
		@@ -159,20 +2097,214 @@
159	2097	}
160	2098	self::$buffer_level = null;
161	2099	}
162	2100
	2101	+ /**
	2102	+ * Are we buffering this request?
	2103	+ *
	2104	+ * Asked by Css_Combine_Buffer, which needs the finished HTML but must not
	2105	+ * open a second buffer when this one is already going to hand it the page
	2106	+ * through `xspeed_cache_final_html`. False here means the request is not
	2107	+ * cacheable — cache off, excluded URL, logged in — and the combiner has to
	2108	+ * provide its own buffer or it silently stops working. (#195)
	2109	+ */
	2110	+ public static function is_buffering(): bool {
	2111	+ return null !== self::$buffer_level;
	2112	+ }
	2113	+
	2114	+ /**
	2115	+ * Is a render-time translation plugin going to wrap our output buffer?
	2116	+ *
	2117	+ * TranslatePress opens its translation buffer on `init` priority 0. We
	2118	+ * open ours on `template_redirect`, which runs much later, so ours nests
	2119	+ * INSIDE theirs. PHP unwinds output buffers LIFO — innermost callback
	2120	+ * first — so `finalize_buffer()` saw the raw, pre-translation HTML and
	2121	+ * cached that, while the live visitor still got the translated bytes from
	2122	+ * TRP's outer buffer.
	2123	+ *
	2124	+ * Result: the first (MISS) visitor to /fr/some-page/ got correct French;
	2125	+ * every visitor after got English body text under a `lang="fr-FR"`
	2126	+ * document, plus TRP's internal `#TRPLINKPROCESSED` link markers, which
	2127	+ * TRP strips at the very end of its own buffer and which therefore leak
	2128	+ * into anything captured from inside it.
	2129	+ *
	2130	+ * Note the ordering cannot be fixed from TRP's side: its
	2131	+ * `trp_start_output_buffer_priority` filter only moves the PRIORITY on
	2132	+ * `init`, and `init` always fires before `template_redirect` whatever the
	2133	+ * priority. The buffer that has to move is ours.
	2134	+ *
	2135	+ * Detected by main class rather than plugin path, so a renamed directory
	2136	+ * or a bundled copy still matches.
	2137	+ */
	2138	+ public static function translation_plugin_active(): bool {
	2139	+ $active = class_exists( 'TRP_Translate_Press' );
	2140	+
	2141	+ /**
	2142	+ * Whether to treat this request as wrapped by a translation buffer.
	2143	+ *
	2144	+ * Lets a site add another render-time translation plugin (or opt out)
	2145	+ * without patching the engine.
	2146	+ *
	2147	+ * @param bool $active
	2148	+ */
	2149	+ return (bool) apply_filters( 'xspeed_translation_plugin_active', $active );
	2150	+ }
	2151	+
	2152	+ /**
	2153	+ * Write the cache file for a request whose output was wrapped by a
	2154	+ * render-time translation plugin.
	2155	+ *
	2156	+ * Registered as a PHP shutdown function (not a WP `shutdown` action) so
	2157	+ * it runs after PHP has unwound the output-buffer stack — by which point
	2158	+ * the translation plugin's callback has transformed the bytes and its
	2159	+ * internal markers are gone.
	2160	+ *
	2161	+ * finalize_buffer() has already applied the status gate, the
	2162	+ * xspeed_cache_final_html filter and HTML minification to the
	2163	+ * untranslated copy and then declined to write it. Here we re-run only
	2164	+ * what's needed on the translated bytes: minify, write, and fire the
	2165	+ * same downstream hooks so Brotli / static-tree listeners behave
	2166	+ * identically to the ordinary path.
	2167	+ */
	2168	+ public static function write_deferred_translated_cache(): void {
	2169	+ $key = self::$deferred_key;
	2170	+ self::$deferred_key = null;
	2171	+
	2172	+ // Release the collected bytes BEFORE the early return, so the static
	2173	+ // is cleared on every path rather than only when a key survived.
	2174	+ $full = self::$translated_output;
	2175	+ self::$translated_output = '';
	2176	+
	2177	+ $completed = self::$render_completed;
	2178	+ self::$render_completed = false;
	2179	+
	2180	+ $asset_stamp = self::$deferred_asset_stamp;
	2181	+ self::$deferred_asset_stamp = null;
	2182	+
	2183	+ if ( null === $key ) {
	2184	+ return;
	2185	+ }
	2186	+
	2187	+ // Did the render actually finish?
	2188	+ //
	2189	+ // This runs as a PHP shutdown function, which fires after a wp_die()
	2190	+ // or a bare exit() just as readily as after a clean render — but in
	2191	+ // those cases finalize_buffer() never returned, so the bytes we hold
	2192	+ // are a page that was cut off partway through. The length and
	2193	+ // TRPLINKPROCESSED checks below don't catch that: a fatal after the
	2194	+ // footer's translated markup is both over 255 bytes and free of TRP
	2195	+ // markers, i.e. truncated but entirely plausible. Caching it would
	2196	+ // freeze a half-rendered page under the real key for the full TTL.
	2197	+ //
	2198	+ // Serving this one URL uncached is the cheap failure; the corrupt
	2199	+ // cache entry is the expensive one.
	2200	+ if ( ! $completed ) {
	2201	+ return;
	2202	+ }
	2203	+
	2204	+ if ( strlen( $full ) < 255 ) {
	2205	+ return;
	2206	+ }
	2207	+
	2208	+ // Refuse to cache a copy still carrying the translation plugin's
	2209	+ // internal link markers. TRP strips these at the very end of its own
	2210	+ // buffer, so their presence means we captured too early — and a
	2211	+ // cached page containing them is SEO-visible damage. Better to serve
	2212	+ // this URL uncached than to freeze broken markup for the full TTL.
	2213	+ if ( false !== strpos( $full, 'TRPLINKPROCESSED' ) ) {
	2214	+ return;
	2215	+ }
	2216	+
	2217	+ $minify_opts = Settings_Manager::get( 'minify' );
	2218	+ if ( ! empty( $minify_opts['minify_html'] ) ) {
	2219	+ $full = Minifier::minify_html( $full );
	2220	+ }
	2221	+ $full = self::signed( $full );
	2222	+
	2223	+ // Per-site directory: on multisite every blog shares this tree, so
	2224	+ // entries are bucketed by host to keep one site's purge from
	2225	+ // sweeping the whole network. (#6)
	2226	+ self::ensure_host_dir();
	2227	+
	2228	+ // Never author a cache entry from a request that carried a query
	2229	+ // string: cache_key() files it under the BARE url, so the params'
	2230	+ // render would be served to every clean-URL visitor (#241).
	2231	+ if ( self::query_string_blocks_write() ) {
	2232	+ return;
	2233	+ }
	2234	+
	2235	+ // Same guard as finalize_buffer(): the translation plugin's buffer
	2236	+ // adds time between render and store, not less.
	2237	+ if ( self::assets_purged_since( $asset_stamp ) ) {
	2238	+ return;
	2239	+ }
	2240	+
	2241	+ $file = self::cache_file_for( $key );
	2242	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- WP_Filesystem requires admin context for credentials; this runs on a frontend shutdown where it's unavailable.
	2243	+ file_put_contents( $file, $full, LOCK_EX );
	2244	+
	2245	+ /** This action is documented in includes/class-cache.php */
	2246	+ do_action( 'xspeed_flat_file_written', $file, $full );
	2247	+
	2248	+ self::write_meta( $key, $full );
	2249	+
	2250	+ // Static tree too, under the same gates finalize_buffer() applies —
	2251	+ // otherwise deferring the write would silently cost translated pages
	2252	+ // the web-server fast path and leave them on the slower drop-in.
	2253	+ // The static tree cannot replay a sidecar. A file served straight by
	2254	+ // the web server carries the headers baked into the rule that serves
	2255	+ // the whole site — the very answer this entry exists because it
	2256	+ // disagreed with. Same reasoning as the status and content-type
	2257	+ // cases: what the fast path cannot replay belongs on the drop-in path.
	2258	+ if ( self::static_rewrite_allowed()
	2259	+ && self::response_is_plain_html()
	2260	+ && array() === self::per_entry_edge_headers() ) {
	2261	+ self::store_static( $full );
	2262	+ }
	2263	+ }
	2264	+
	2265	+ /**
	2266	+ * Did a purge delete minified or combined files after $stamp was taken?
	2267	+ *
	2268	+ * @param string|null $stamp Minifier::purge_stamp() when the render began,
	2269	+ * or null when no snapshot was taken.
	2270	+ */
	2271	+ private static function assets_purged_since( ?string $stamp ): bool {
	2272	+ if ( null === $stamp || ! class_exists( '\\XSpeed\\Minifier' ) ) {
	2273	+ return false;
	2274	+ }
	2275	+ return Minifier::purge_stamp() !== $stamp;
	2276	+ }
	2277	+
163	2278	public static function should_cache() {
	2279	+ // Reset first: a single request only reaches this once (the sole
	2280	+ // caller is maybe_start_cache()), but tests and any future caller
	2281	+ // must never inherit the previous request's verdict.
	2282	+ self::$status_header = '';
	2283	+ self::$bypass_reason = '';
	2284	+ self::$edge_headers = array();
	2285	+ self::$per_entry_edge = null;
	2286	+ // Under PHP-FPM a process serves one request and this is moot. Under
	2287	+ // a persistent worker runtime it is not: without it, an answer
	2288	+ // resolved from one visitor's forgeable headers would be reused for
	2289	+ // every later request the worker handles.
	2290	+ Edge_Provider::forget();
	2291	+
164	2292	$opts = Settings::get();
165	2293	if ( empty( $opts['cache_enabled'] ) ) {
166		- return false;
	2294	+ return self::bypass( 'cache-disabled' );
167	2295	}
168	2296
169		- if ( is_user_logged_in() || is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
170		- return false;
	2297	+ if ( is_user_logged_in() ) {
	2298	+ return self::bypass( 'logged-in' );
171	2299	}
172	2300
	2301	+ if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
	2302	+ return self::bypass( 'non-frontend' );
	2303	+ }
	2304	+
173	2305	if ( defined( 'DONOTCACHEPAGE' ) && DONOTCACHEPAGE ) {
174		- return false;
	2306	+ return self::bypass( 'donotcachepage' );
175	2307	}
176	2308
177	2309	// All exclusion knobs now owned by CacheModule.
178	2310	$cache_opts = Settings_Manager::get( 'cache' );
		@@ -178,9 +2310,9 @@
178	2310	$cache_opts = Settings_Manager::get( 'cache' );
179	2311
180	2312	$method = isset( $_SERVER['REQUEST_METHOD'] ) ? strtoupper( sanitize_text_field( wp_unslash( $_SERVER['REQUEST_METHOD'] ) ) ) : '';
181	2313	if ( 'GET' !== $method ) {
182		- return false;
	2314	+ return self::bypass( 'non-get' );
183	2315	}
184	2316
185	2317	// Search-results requests carry a `s` query param, which the
186	2318	// query-string gate below would normally reject as "dynamic". An
		@@ -207,13 +2339,35 @@
207	2339	* @param bool $cache_feed Whether to cache this feed request.
208	2340	*/
209	2341	$cache_feed = $is_feed_request && (bool) apply_filters( 'xspeed_should_cache_feed', false );
210	2342
	2343	+ // WordPress's virtual robots.txt (and virtual favicon) are not HTML:
	2344	+ // caching one runs it through the whole HTML pipeline, which stamped
	2345	+ // the footer comment onto text/plain and let HTML minification
	2346	+ // collapse robots.txt to a single line — a line-based format, so
	2347	+ // every directive after the first was lost and crawlers read an
	2348	+ // invalid file. No opt-in filter here: there is no correct way to
	2349	+ // treat these as pages. (Reported live on a customer site.)
	2350	+ if ( ( function_exists( 'is_robots' ) && is_robots() )
	2351	+ || ( function_exists( 'is_favicon' ) && is_favicon() ) ) {
	2352	+ return self::bypass( 'non-html' );
	2353	+ }
	2354	+
211	2355	// Query string handling: anything OUTSIDE the ignored-params
212	2356	// allow-list (utm_*, fbclid, gclid by default) means a unique
213	2357	// request that we don't want to share with the canonical cache
214	2358	// entry. Skip cache rather than poison the key.
215		- $query_raw = isset( $_SERVER['QUERY_STRING'] ) ? sanitize_text_field( wp_unslash( $_SERVER['QUERY_STRING'] ) ) : '';
	2359	+ //
	2360	+ // Parse the RAW query string, NOT a sanitize_text_field() copy:
	2361	+ // that filter strips percent-encoded octets (%XX), so `?%73=…`
	2362	+ // would lose its `s` key here while WordPress still decodes it to
	2363	+ // a search request — the gate would wave the request through and
	2364	+ // cache_key() would file the search page under the bare URL,
	2365	+ // letting an attacker poison the homepage cache with `/?%73=<spam>`.
	2366	+ // parse_str() does its own urldecoding, matching WP's own parse, and
	2367	+ // only the KEYS are used below (fed to Glob_Matcher → preg_match,
	2368	+ // never echoed or executed), so no sanitization is needed here.
	2369	+ $query_raw = isset( $_SERVER['QUERY_STRING'] ) ? wp_unslash( $_SERVER['QUERY_STRING'] ) : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- see note above: parse_str() urldecodes to match WP; only keys are consumed, via preg_match, never output.
216	2370	if ( '' !== $query_raw ) {
217	2371	$ignored = is_array( $cache_opts['ignored_query_params'] ?? null ) ? $cache_opts['ignored_query_params'] : array();
218	2372	parse_str( $query_raw, $params );
219	2373	foreach ( $params as $key => $_ ) {
		@@ -222,23 +2376,24 @@
222	2376	continue;
223	2377	}
224	2378	// Allow query-form feed params through when feed caching opted
225	2379	// this request in (?feed=rss2 / &withcomments=1 on feeds).
226		- if ( $cache_feed && in_array( $key, array( 'feed', 'withcomments', 'withoutcomments' ), true ) ) {
	2380	+ if ( $cache_feed && in_array( $key, self::FEED_QUERY_PARAMS, true ) ) {
227	2381	continue;
228	2382	}
229	2383	if ( ! self::query_key_is_ignored( (string) $key, $ignored ) ) {
230		- return false;
	2384	+ // Slug only — never the param name, which is attacker-
	2385	+ // controlled and would be reflected into a header.
	2386	+ return self::bypass( 'query-param' );
231	2387	}
232	2388	}
233	2389	}
234	2390
235		- $request_uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
236		- $path = (string) strtok( $request_uri, '?' );
	2391	+ $path = self::request_path();
237	2392
238	2393	$excluded_urls = is_array( $cache_opts['excluded_urls'] ?? null ) ? $cache_opts['excluded_urls'] : array();
239		- if ( ! $cache_feed && Glob_Matcher::any_match( $excluded_urls, $path ) ) {
240		- return false;
	2394	+ if ( ! $cache_feed && self::path_matches_exclusions( $excluded_urls, $path ) ) {
	2395	+ return self::bypass( 'excluded-url' );
241	2396	}
242	2397
243	2398	// Cookie-based exclusion. We only check cookie NAMES (matching
244	2399	// values would leak content-sensitive logic into the cache key
		@@ -245,10 +2400,21 @@
245	2400	// rules); presence of any matching cookie name skips cache.
246	2401	$excluded_cookies = is_array( $cache_opts['excluded_cookies'] ?? null ) ? $cache_opts['excluded_cookies'] : array();
247	2402	if ( ! empty( $excluded_cookies ) && ! empty( $_COOKIE ) ) {
248	2403	foreach ( array_keys( $_COOKIE ) as $cookie_name ) {
	2404	+ // Our own bypass cookie is a RECORD of a previous verdict, not
	2405	+ // evidence about this visitor, so it never gets a vote here.
	2406	+ // Letting it match made the verdict self-confirming: once set,
	2407	+ // it produced `excluded-cookie` forever, which re-set it, and
	2408	+ // no later request could ever re-evaluate the visitor on the
	2409	+ // rules that actually describe them. The web server still acts
	2410	+ // on the cookie without booting PHP; when PHP does boot it is
	2411	+ // authoritative and re-decides from scratch. (#218)
	2412	+ if ( Server_Rules::BYPASS_COOKIE === $cookie_name ) {
	2413	+ continue;
	2414	+ }
249	2415	if ( Glob_Matcher::any_match( $excluded_cookies, (string) $cookie_name ) ) {
250		- return false;
	2416	+ return self::bypass( 'excluded-cookie' );
251	2417	}
252	2418	}
253	2419	}
254	2420
		@@ -259,9 +2425,9 @@
259	2425	if ( ! empty( $bypass_uas ) ) {
260	2426	$ua = isset( $_SERVER['HTTP_USER_AGENT'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_USER_AGENT'] ) ) : '';
261	2427	foreach ( $bypass_uas as $needle ) {
262	2428	if ( '' !== $needle && false !== stripos( $ua, (string) $needle ) ) {
263		- return false;
	2429	+ return self::bypass( 'user-agent' );
264	2430	}
265	2431	}
266	2432	}
267	2433
		@@ -268,9 +2434,9 @@
268	2434	// Per-post override (Phase 3.4). Honored only on singular
269	2435	// post-context requests — archives / 404s / taxonomies use the
270	2436	// global policy above.
271	2437	if ( Cache_Rules::should_skip_for_post( Cache_Rules::current_post_id() ) ) {
272		- return false;
	2438	+ return self::bypass( 'post-excluded' );
273	2439	}
274	2440
275	2441	/**
276	2442	* Final say on whether the current request is cacheable.
		@@ -290,9 +2456,16 @@
290	2456	* advanced-cache.php.
291	2457	*
292	2458	* @param bool $should_cache Whether to cache the current request.
293	2459	*/
294		- return (bool) apply_filters( 'xspeed_should_cache', true );
	2460	+ if ( ! apply_filters( 'xspeed_should_cache', true ) ) {
	2461	+ // One slug for every listener — a third-party callback name is
	2462	+ // not ours to put in a response header. Which listener vetoed is
	2463	+ // a WP_DEBUG-level question the filter itself can answer.
	2464	+ return self::bypass( 'filtered' );
	2465	+ }
	2466	+
	2467	+ return true;
295	2468	}
296	2469
297	2470	/**
298	2471	* Whether the current request is a 404 we may cache.
		@@ -336,8 +2509,99 @@
336	2509	* search_term() / cache_key()) so different searches stay distinct.
337	2510	* The xspeed-pro search cache flips the filter; Free never caches
338	2511	* search results on its own.
339	2512	*/
	2513	+ /**
	2514	+ * Whether this response was rendered for a query string and therefore
	2515	+ * must not be STORED under the bare-URL key.
	2516	+ *
	2517	+ * should_cache() lets a request through when every key is on the
	2518	+ * `ignored_query_params` allow-list, and cache_key() then drops the
	2519	+ * query string so `/post` and `/post?utm_source=x` share one entry.
	2520	+ * Sharing on READ is the point of the allow-list and stays. Sharing on
	2521	+ * WRITE is a cache-poisoning vector: the response was rendered *with*
	2522	+ * those params, and WordPress reflects REQUEST_URI into form actions,
	2523	+ * share links, canonical helpers and plugin smart tags. One anonymous
	2524	+ * GET to a cold URL therefore freezes an attacker-chosen variant under
	2525	+ * the clean URL's key, served for the whole TTL by the drop-in and by
	2526	+ * the web server — neither of which runs these checks (issue #241).
	2527	+ *
	2528	+ * The allow-list keeps its benefit: a visitor arriving on
	2529	+ * `?utm_source=…` is still SERVED the canonical cached entry. Only the
	2530	+ * write is skipped, so the entry is authored by a clean request.
	2531	+ *
	2532	+ * This is the same reasoning as the `should_cache_search()` guard in
	2533	+ * store_static() (#191), generalised to the allow-listed params.
	2534	+ */
	2535	+ public static function request_has_query_string(): bool {
	2536	+ $query = isset( $_SERVER['QUERY_STRING'] )
	2537	+ ? (string) wp_unslash( $_SERVER['QUERY_STRING'] ) // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- only tested for emptiness; never echoed, stored or used as a path.
	2538	+ : '';
	2539	+
	2540	+ return '' !== trim( $query );
	2541	+ }
	2542	+
	2543	+ /**
	2544	+ * Whether this request's query string is empty or holds only params the
	2545	+ * cache ignores (`ignored_query_params`, utm_* and the like), so the
	2546	+ * page is the one the bare URL serves.
	2547	+ *
	2548	+ * The same test should_cache() applies, without its search and feed
	2549	+ * exceptions: those are keyed apart from the bare URL.
	2550	+ */
	2551	+ public static function query_has_only_ignored_params(): bool {
	2552	+ $query_raw = isset( $_SERVER['QUERY_STRING'] ) ? wp_unslash( $_SERVER['QUERY_STRING'] ) : ''; // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- as in should_cache(): only keys are read, via preg_match.
	2553	+ if ( '' === trim( (string) $query_raw ) ) {
	2554	+ return true;
	2555	+ }
	2556	+ $cache_opts = Settings_Manager::get( 'cache' );
	2557	+ $ignored = is_array( $cache_opts['ignored_query_params'] ?? null ) ? $cache_opts['ignored_query_params'] : array();
	2558	+ parse_str( (string) $query_raw, $params );
	2559	+ foreach ( $params as $key => $_ ) {
	2560	+ if ( ! self::query_key_is_ignored( (string) $key, $ignored ) ) {
	2561	+ return false;
	2562	+ }
	2563	+ }
	2564	+ return true;
	2565	+ }
	2566	+
	2567	+ /**
	2568	+ * Would authoring a cache entry from THIS request file a query-string
	2569	+ * render under the bare URL?
	2570	+ *
	2571	+ * The one predicate both write sites ask, so they cannot drift.
	2572	+ *
	2573	+ * Two shapes are exempt because cache_key() does NOT drop their query —
	2574	+ * it folds the distinguishing part into the key, so each variant gets
	2575	+ * its own entry and none is filed under the bare URL:
	2576	+ *
	2577	+ * - searches, keyed by `|s=<term>` (#191)
	2578	+ * - feeds, keyed by `|feed=<type>` — `/?feed=rss2` is the ONLY feed URL
	2579	+ * core generates on plain permalinks, so treating it as poisonable
	2580	+ * made feed caching a no-op on exactly the sites that need it
	2581	+ *
	2582	+ * @return bool True when the write must be skipped.
	2583	+ */
	2584	+ public static function query_string_blocks_write(): bool {
	2585	+ if ( ! self::request_has_query_string() ) {
	2586	+ return false;
	2587	+ }
	2588	+
	2589	+ if ( self::should_cache_search() ) {
	2590	+ return false;
	2591	+ }
	2592	+
	2593	+ // Feed caching is opt-in, via the same filter should_cache() reads
	2594	+ // to admit the feed params in the first place.
	2595	+ if ( function_exists( 'is_feed' ) && is_feed()
	2596	+ && (bool) apply_filters( 'xspeed_should_cache_feed', false )
	2597	+ ) {
	2598	+ return false;
	2599	+ }
	2600	+
	2601	+ return true;
	2602	+ }
	2603	+
340	2604	public static function should_cache_search(): bool {
341	2605	if ( ! function_exists( 'is_search' ) || ! is_search() ) {
342	2606	return false;
343	2607	}
		@@ -377,15 +2641,251 @@
377	2641	}
378	2642
379	2643	/**
380	2644	* Is this query-string key on the ignored-params allow-list? Supports
381		- * trailing-star globs (`utm_*` matches `utm_source`, `utm_medium`,
382		- * etc.) so users don't have to enumerate every UTM variant.
	2645	+ * globs (`utm_*` matches `utm_source`, `utm_medium`, etc.) so users
	2646	+ * don't have to enumerate every UTM variant, and `~regex`.
	2647	+ *
	2648	+ * Matching is whole-name, not "contains" — a param name is an
	2649	+ * identifier, not a path. Under the old contains match the shipped
	2650	+ * default `ref` also swallowed `preference`, `product_ref` and
	2651	+ * `referrer`: those params were dropped from the cache key, so
	2652	+ * `/shop?preference=1` was served — and, on a cold entry, WRITTEN as —
	2653	+ * `/shop`. Same for `_ga` vs `_gallery`, and for the unanchored
	2654	+ * `~utm_…` default vs `my_utm_source`. A param name that is genuinely
	2655	+ * unknown now bypasses the cache, which is the safe direction.
383	2656	*/
384	2657	private static function query_key_is_ignored( string $key, array $ignored ): bool {
385		- return Glob_Matcher::any_match( $ignored, $key );
	2658	+ if ( in_array( $key, self::NEVER_IGNORED_QUERY_PARAMS, true ) ) {
	2659	+ return false;
	2660	+ }
	2661	+ return Glob_Matcher::any_match_name( $ignored, $key );
386	2662	}
387	2663
	2664	+ /**
	2665	+ * Query params no ignored-params entry can match, glob or regex.
	2666	+ *
	2667	+ * A measuring request asks for the page as it is before optimisation
	2668	+ * (`xspeed_css=off`), with a one-time value (`xspeed_nc`) so no cache
	2669	+ * has a copy of it. The answer must be rendered for that request. A
	2670	+ * list entry such as `xspeed_*` or `*` would make both params
	2671	+ * decoration: the drop-in would serve the canonical, already-optimised
	2672	+ * entry before any plugin loads, and the measurement would describe
	2673	+ * the optimised page instead of the source.
	2674	+ */
	2675	+ public const NEVER_IGNORED_QUERY_PARAMS = array( 'xspeed_css', 'xspeed_nc' );
	2676	+
	2677	+ /**
	2678	+ * The params a query-form feed may carry (`/?feed=rss2`) once feed
	2679	+ * caching has opted the request in. should_cache() lets them through,
	2680	+ * and serves_query_variant() holds a HIT that carries one.
	2681	+ */
	2682	+ private const FEED_QUERY_PARAMS = array( 'feed', 'withcomments', 'withoutcomments' );
	2683	+
	2684	+ /**
	2685	+ * The one spelling of a URL path that every cache key is built from.
	2686	+ *
	2687	+ * WordPress stores a non-ASCII slug percent-encoded, so a page called
	2688	+ * `關於我們` is requested as `/%e9%97%9c%e6%96%bc%e6%88%91%e5%80%91/`. The
	2689	+ * same page also arrives as `/%E9%97%9C…/` (what a browser sends for an
	2690	+ * address typed or pasted into it) and as raw UTF-8 bytes. WordPress
	2691	+ * renders the same page for all three, so they get one key: escapes are
	2692	+ * lowercased (WordPress's own spelling, so a permalink comes back
	2693	+ * unchanged) and any byte outside printable ASCII is escaped the same way.
	2694	+ * Null bytes are dropped, as the drop-in does.
	2695	+ *
	2696	+ * Nothing is decoded. `/ab%6Fut/` stays a separate entry from `/about/`.
	2697	+ * Only spellings of the same bytes are merged, because merging spellings
	2698	+ * WordPress may route differently would let one page be served for
	2699	+ * another. A printable-ASCII path with no escapes comes back unchanged,
	2700	+ * so ordinary pages keep the keys they had.
	2701	+ *
	2702	+ * The path used to go through sanitize_text_field(), which deletes every
	2703	+ * `%XX` octet: `/第九屆-當代藝術-tagboat-award-特展/` was keyed as
	2704	+ * `/--tagboat-award-/`, every page whose slug differed only in non-ASCII
	2705	+ * characters shared one entry, and an all-non-ASCII slug became `//`,
	2706	+ * which store_static() wrote over the home page's static file.
	2707	+ *
	2708	+ * The drop-in carries a copy of this transform, because it runs before
	2709	+ * WordPress and this class load. Change both together.
	2710	+ *
	2711	+ * @param string $path A URL path, without the query string.
	2712	+ */
	2713	+ public static function normalize_path( string $path ): string {
	2714	+ return self::path_with_escape_case( $path, false );
	2715	+ }
	2716	+
	2717	+ /**
	2718	+ * The spellings of one path that a cache in front of the site may hold.
	2719	+ *
	2720	+ * xSpeed keys every escape spelling of a path as one entry
	2721	+ * (normalize_path()). A CDN does not: Cloudflare keeps `/%E9%97%9C…/`,
	2722	+ * the spelling a browser sends, apart from `/%e9%97%9c…/`, the spelling
	2723	+ * of WordPress's own links. A purge that named one left the other
	2724	+ * serving the old page until its edge lifetime ran out.
	2725	+ *
	2726	+ * Returns the path as given, then normalize_path()'s spelling (lower-case
	2727	+ * escapes), then the same with upper-case escapes. Both are built from
	2728	+ * the path the local sweep cleared, so a cache in front is never asked
	2729	+ * about a page xSpeed did not purge. Duplicates drop out, so a path with
	2730	+ * no escapes has one spelling. Trailing-slash forms are the caller's job.
	2731	+ *
	2732	+ * @param string $path A URL path, without the query string.
	2733	+ * @return string[]
	2734	+ */
	2735	+ public static function escape_spellings( string $path ): array {
	2736	+ return array_values(
	2737	+ array_unique(
	2738	+ array( $path, self::path_with_escape_case( $path, false ), self::path_with_escape_case( $path, true ) )
	2739	+ )
	2740	+ );
	2741	+ }
	2742	+
	2743	+ /**
	2744	+ * normalize_path() with the escapes in the case asked for.
	2745	+ *
	2746	+ * @param string $path A URL path, without the query string.
	2747	+ * @param bool $upper Upper-case escapes, or lower (the key's spelling).
	2748	+ */
	2749	+ private static function path_with_escape_case( string $path, bool $upper ): string {
	2750	+ return (string) preg_replace_callback(
	2751	+ '/%[0-9a-fA-F]{2}|[^\x21-\x7E]/',
	2752	+ static function ( array $m ) use ( $upper ): string {
	2753	+ $escape = '%' === $m[0][0] ? $m[0] : sprintf( '%%%02x', ord( $m[0] ) );
	2754	+ return $upper ? strtoupper( $escape ) : strtolower( $escape );
	2755	+ },
	2756	+ str_replace( "\0", '', $path )
	2757	+ );
	2758	+ }
	2759	+
	2760	+ /**
	2761	+ * Percent-encode every byte 0x80 and up, lowercase hex.
	2762	+ *
	2763	+ * @param string $value A path or a whole URL.
	2764	+ */
	2765	+ private static function encode_non_ascii( string $value ): string {
	2766	+ return (string) preg_replace_callback(
	2767	+ '/[\x80-\xff]/',
	2768	+ static function ( array $m ): string {
	2769	+ return '%' . bin2hex( $m[0] );
	2770	+ },
	2771	+ $value
	2772	+ );
	2773	+ }
	2774	+
	2775	+ /**
	2776	+ * Where a URL path lives in the static tree, relative to the host
	2777	+ * directory, with a leading slash and no trailing one ('' for the home
	2778	+ * page). Null when the path must not be written there.
	2779	+ *
	2780	+ * Decoded, because that is what the web server looks up: nginx builds the
	2781	+ * file name from `$uri` and Apache from `%{REQUEST_URI}`, and both hold
	2782	+ * the decoded path. A file stored under the encoded name is never found.
	2783	+ *
	2784	+ * Decoding is only safe for the escapes WordPress itself writes, which
	2785	+ * encode the bytes of non-ASCII letters (0x80 and up). An escaped ASCII
	2786	+ * byte is refused, because the server decodes it before the lookup:
	2787	+ * `%2F` would become a directory, `%2E%2E` a parent, and `%6F` would
	2788	+ * make `/ab%6Fut/` and `/about/` share one file although they are
	2789	+ * separate cache entries. The decoded path must also be valid UTF-8, with
	2790	+ * no control byte, backslash or `%`, no `..` anywhere and no `.`
	2791	+ * segment. A refused page is still cached by the drop-in; it only loses
	2792	+ * the no-PHP path.
	2793	+ *
	2794	+ * @param string $path A URL path, without the query string.
	2795	+ */
	2796	+ public static function static_path( string $path ): ?string {
	2797	+ if ( '' === $path || false !== strpos( $path, "\0" ) ) {
	2798	+ return null;
	2799	+ }
	2800	+ if ( preg_match_all( '/%([0-9a-fA-F]{2})/', $path, $escapes ) ) {
	2801	+ foreach ( $escapes[1] as $hex ) {
	2802	+ if ( hexdec( $hex ) < 0x80 ) {
	2803	+ return null;
	2804	+ }
	2805	+ }
	2806	+ }
	2807	+ $decoded = rawurldecode( $path );
	2808	+ if ( 1 !== preg_match( '//u', $decoded ) || preg_match( '/[\x00-\x1f\x7f\\\\%]/', $decoded ) ) {
	2809	+ return null;
	2810	+ }
	2811	+ $decoded = (string) preg_replace( '#/+#', '/', $decoded );
	2812	+ if ( false !== strpos( $decoded, '..' ) || preg_match( '#(^|/)\.(/|$)#', $decoded ) ) {
	2813	+ return null;
	2814	+ }
	2815	+ return rtrim( $decoded, '/' );
	2816	+ }
	2817	+
	2818	+ /**
	2819	+ * The current request's path, normalized, without the query string.
	2820	+ *
	2821	+ * @param string $fallback Returned when the server sent no REQUEST_URI.
	2822	+ */
	2823	+ private static function request_path( string $fallback = '' ): string {
	2824	+ if ( ! isset( $_SERVER['REQUEST_URI'] ) ) {
	2825	+ return $fallback;
	2826	+ }
	2827	+ // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- normalize_path() is the sanitizer. sanitize_text_field() deletes percent-encoded octets and broke every non-ASCII slug (see normalize_path()). The value is hashed, matched, or checked by static_path() before it touches the disk.
	2828	+ $uri = (string) wp_unslash( $_SERVER['REQUEST_URI'] );
	2829	+ return self::normalize_path( (string) strtok( $uri, '?' ) );
	2830	+ }
	2831	+
	2832	+ /**
	2833	+ * An Excluded URLs entry with its escapes in lower case.
	2834	+ *
	2835	+ * The request path is matched in normalize_path()'s spelling, so an entry
	2836	+ * copied from Chrome's address bar (`/%E8%81%AF…/`) never matched it.
	2837	+ * Only `%XX` sequences change; the rest of the entry, including a `~`
	2838	+ * regex, is left as typed.
	2839	+ *
	2840	+ * @param string $pattern One Excluded URLs entry.
	2841	+ */
	2842	+ public static function normalize_exclusion( string $pattern ): string {
	2843	+ return (string) preg_replace_callback(
	2844	+ '/%[0-9a-fA-F]{2}/',
	2845	+ static function ( array $m ): string {
	2846	+ return strtolower( $m[0] );
	2847	+ },
	2848	+ $pattern
	2849	+ );
	2850	+ }
	2851	+
	2852	+ /**
	2853	+ * Does an exclusion list match this path, in either spelling?
	2854	+ *
	2855	+ * An admin may paste an exclusion as `/購物車`, as WordPress spells it, or
	2856	+ * as Chrome shows it in upper case. The entry's escapes are lowercased to
	2857	+ * match the path, and the decoded path is tried too, which is also what
	2858	+ * the nginx rule matches (`$uri` is decoded).
	2859	+ *
	2860	+ * @param string[] $patterns Exclusion entries.
	2861	+ * @param string $path Output of normalize_path().
	2862	+ */
	2863	+ private static function path_matches_exclusions( array $patterns, string $path ): bool {
	2864	+ $patterns = array_map(
	2865	+ static function ( $pattern ): string {
	2866	+ return self::normalize_exclusion( (string) $pattern );
	2867	+ },
	2868	+ $patterns
	2869	+ );
	2870	+ if ( Glob_Matcher::any_match( $patterns, $path ) ) {
	2871	+ return true;
	2872	+ }
	2873	+ $decoded = rawurldecode( $path );
	2874	+ return $decoded !== $path && Glob_Matcher::any_match( $patterns, $decoded );
	2875	+ }
	2876	+
	2877	+ /**
	2878	+ * Whether this request's path matches an Excluded URLs list, by the
	2879	+ * page cache's own rule. Turbo Render asks it when it buffers the page
	2880	+ * itself (page cache off), so both read an entry the same way.
	2881	+ *
	2882	+ * @param string[] $patterns Exclusion entries.
	2883	+ */
	2884	+ public static function request_matches_exclusions( array $patterns ): bool {
	2885	+ return self::path_matches_exclusions( $patterns, self::request_path() );
	2886	+ }
	2887	+
388	2888	public static function cache_key() {
389	2889	$host = isset( $_SERVER['HTTP_HOST'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_HOST'] ) ) : 'default';
390	2890
391	2891	// Cacheable 404s share ONE generic per-host entry — keying them by
		@@ -395,14 +2895,13 @@
395	2895	if ( self::should_cache_404() ) {
396	2896	return md5( $host . '|404' );
397	2897	}
398	2898
399		- $uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '/';
400	2899	// Strip the query string from the key so /post and /post?utm_*=…
401	2900	// share the same cache entry. should_cache() above already
402	2901	// rejected requests with non-ignored params, so by the time we
403	2902	// build the key the only params left are safe to drop.
404		- $uri = (string) strtok( $uri, '?' );
	2903	+ $uri = self::request_path( '/' );
405	2904
406	2905	// Optional device bucket: when mobile_separate is on, mobile and
407	2906	// desktop responses live in different cache files so themes that
408	2907	// serve different HTML by device (AMP, WPtouch, Jetpack mobile)
		@@ -459,10 +2958,300 @@
459	2958	}
460	2959	return (bool) preg_match( '/(Mobile|Android|Silk\/|Kindle|BlackBerry|Opera Mini|Opera Mobi)/i', $ua );
461	2960	}
462	2961
	2962	+ /**
	2963	+ * Filesystem-safe directory name for a host, or '' when unusable.
	2964	+ *
	2965	+ * The charset MUST match the static tree (store_static()) and the
	2966	+ * drop-in's own copy, or the paths disagree about where an entry lives.
	2967	+ * The colon of `host:port` is stripped: it is legal in a Host header but
	2968	+ * not portable in a path.
	2969	+ *
	2970	+ * @param string $host Raw host, e.g. from HTTP_HOST.
	2971	+ * @return string Safe directory segment, or '' if nothing usable remains.
	2972	+ */
	2973	+ /**
	2974	+ * The host segment of the STATIC tree — `xspeed-static/<host>/…`, which
	2975	+ * the web server resolves without PHP.
	2976	+ *
	2977	+ * Different from host_dir(): here the port is folded INTO the segment
	2978	+ * (`localhost:8080` → `localhost8080`) rather than dropped, because the
	2979	+ * generated server rules have to reproduce this from their own variables
	2980	+ * and nginx's `$host` has no port to drop — see the `$xspeed_host`
	2981	+ * derivation in nginx_snippet(). Shared by the write and the purge so the
	2982	+ * two can't drift; when they did, purging a page on a ported host deleted
	2983	+ * nothing and the stale copy kept being served by the rewrite.
	2984	+ */
	2985	+ public static function static_host_dir( string $host ): string {
	2986	+ return (string) preg_replace( '/[^a-zA-Z0-9.\-]/', '', $host );
	2987	+ }
	2988	+
	2989	+ public static function host_dir( string $host ): string {
	2990	+ $host = str_replace( "\0", '', $host );
	2991	+ // Drop the port BEFORE filtering, or `example.com:8080` collapses to
	2992	+ // `example.com8080` — which both loses the boundary and could collide
	2993	+ // with a real host of that name.
	2994	+ $colon = strpos( $host, ':' );
	2995	+ if ( false !== $colon ) {
	2996	+ $host = substr( $host, 0, $colon );
	2997	+ }
	2998	+ $host = preg_replace( '/[^a-zA-Z0-9.\-]/', '', $host );
	2999	+ // Collapse any run of dots so no traversal sequence can survive the
	3000	+ // charset filter (`a/../b` would otherwise reduce to `a..b`).
	3001	+ $host = preg_replace( '/\.{2,}/', '.', (string) $host );
	3002	+ $host = trim( (string) $host, '.-' );
	3003	+ return '' === $host ? '' : $host;
	3004	+ }
	3005	+
	3006	+ /**
	3007	+ * The per-site bucket a cache entry belongs to: `<host>` on a single
	3008	+ * site, `<host>/<path-prefix>` for a subdirectory multisite blog.
	3009	+ *
	3010	+ * On multisite every blog shares one cache directory, and a flat md5
	3011	+ * filename carries no clue which site wrote it — so purging one subsite
	3012	+ * swept the whole network cold. (#6)
	3013	+ *
	3014	+ * Host alone is NOT enough: a subdirectory network (the common layout)
	3015	+ * puts every blog on the same host, so `example.com/` and
	3016	+ * `example.com/siteb/` would share a bucket and keep purging each other.
	3017	+ * The path prefix is what separates them, and it is derivable from the
	3018	+ * REQUEST_URI alone — which matters because the drop-in must compute
	3019	+ * this identical value before WordPress (and get_blog_details()) exist.
	3020	+ *
	3021	+ * Subdomain and domain-mapped networks differ by host already, so they
	3022	+ * get a bare host bucket and are unaffected.
	3023	+ *
	3024	+ * @param string $host Raw host.
	3025	+ * @param string $uri Raw REQUEST_URI (query string is ignored).
	3026	+ * @return string Bucket path, always non-empty.
	3027	+ */
	3028	+ public static function site_bucket( string $host, string $uri ): string {
	3029	+ $dir = self::host_dir( $host );
	3030	+ if ( '' === $dir ) {
	3031	+ $dir = 'default';
	3032	+ }
	3033	+
	3034	+ $prefix = self::site_path_prefix();
	3035	+ return '' === $prefix ? $dir : $dir . '/' . $prefix;
	3036	+ }
	3037	+
	3038	+ /**
	3039	+ * The current blog's path prefix as a single safe segment ('' for the
	3040	+ * root blog or a non-multisite install). `/siteb/` becomes `siteb`;
	3041	+ * a nested `/a/b/` becomes `a-b` so the bucket stays one level deep.
	3042	+ *
	3043	+ * Written to a sidecar for the drop-in by sync_site_paths().
	3044	+ */
	3045	+ public static function site_path_prefix(): string {
	3046	+ if ( ! function_exists( 'is_multisite' ) || ! is_multisite() ) {
	3047	+ return '';
	3048	+ }
	3049	+ if ( function_exists( 'is_subdomain_install' ) && is_subdomain_install() ) {
	3050	+ return ''; // Hosts already differ; no prefix needed.
	3051	+ }
	3052	+ $path = function_exists( 'get_blog_details' ) ? (string) get_blog_details()->path : '/';
	3053	+ return self::path_prefix_segment( $path );
	3054	+ }
	3055	+
	3056	+ /**
	3057	+ * The bucket an arbitrary URL's cache entry lives in.
	3058	+ *
	3059	+ * `site_bucket()` answers for the CURRENT request; this answers for a URL
	3060	+ * that may belong to another blog entirely — which is what a per-URL purge
	3061	+ * is usually doing (WP-CLI, cron, the MCP tool, a network-admin action).
	3062	+ *
	3063	+ * The blog is resolved from the URL itself: on a subdirectory network
	3064	+ * `get_blog_details()` is asked which blog owns `<host><path>`, and its
	3065	+ * registered path becomes the prefix. Deriving the prefix from the URL's
	3066	+ * first path segment directly would be wrong — `/shop/` on the main blog
	3067	+ * is a page, not a subsite, and would send the purge into a bucket that
	3068	+ * does not exist. (QA B2 on #166)
	3069	+ *
	3070	+ * @param string $host Host of the URL being purged.
	3071	+ * @param string $path Path of the URL being purged.
	3072	+ * @return string Bucket path, always non-empty.
	3073	+ */
	3074	+ public static function bucket_for_url( string $host, string $path ): string {
	3075	+ $dir = self::host_dir( $host );
	3076	+ if ( '' === $dir ) {
	3077	+ $dir = 'default';
	3078	+ }
	3079	+
	3080	+ if ( ! function_exists( 'is_multisite' ) || ! is_multisite() ) {
	3081	+ return $dir;
	3082	+ }
	3083	+ if ( function_exists( 'is_subdomain_install' ) && is_subdomain_install() ) {
	3084	+ return $dir; // Hosts already differ; no prefix.
	3085	+ }
	3086	+ if ( ! function_exists( 'get_blog_details' ) ) {
	3087	+ return $dir;
	3088	+ }
	3089	+
	3090	+ // Longest registered blog path that prefixes this URL wins, so
	3091	+ // `/one/2026/post/` resolves to blog `/one/` and not to the root blog.
	3092	+ $blog = self::blog_for_path( $host, $path );
	3093	+ if ( null === $blog ) {
	3094	+ return $dir;
	3095	+ }
	3096	+ $prefix = self::path_prefix_segment( (string) $blog );
	3097	+ return '' === $prefix ? $dir : $dir . '/' . $prefix;
	3098	+ }
	3099	+
	3100	+ /**
	3101	+ * The registered path of the blog that owns `<host><path>`, or null.
	3102	+ *
	3103	+ * Uses get_blog_details() with a domain/path pair rather than scanning
	3104	+ * every blog, so a large network costs one lookup per candidate segment
	3105	+ * instead of a full table read.
	3106	+ */
	3107	+ private static function blog_for_path( string $host, string $path ): ?string {
	3108	+ $segments = array_values( array_filter( explode( '/', trim( $path, '/' ) ) ) );
	3109	+
	3110	+ // Try the longest candidate first: /a/b/ before /a/ before /.
	3111	+ for ( $take = min( count( $segments ), 2 ); $take >= 1; $take-- ) {
	3112	+ $candidate = '/' . implode( '/', array_slice( $segments, 0, $take ) ) . '/';
	3113	+ $details = get_blog_details(
	3114	+ array(
	3115	+ 'domain' => $host,
	3116	+ 'path' => $candidate,
	3117	+ ),
	3118	+ false
	3119	+ );
	3120	+ if ( $details && ! empty( $details->path ) ) {
	3121	+ return (string) $details->path;
	3122	+ }
	3123	+ }
	3124	+ return null;
	3125	+ }
	3126	+
	3127	+ /**
	3128	+ * Normalise a blog path ('/', '/siteb/', '/a/b/') into a single
	3129	+ * filesystem-safe segment. Shared with the drop-in's copy.
	3130	+ */
	3131	+ public static function path_prefix_segment( string $path ): string {
	3132	+ $path = trim( str_replace( "\0", '', $path ), '/' );
	3133	+ if ( '' === $path ) {
	3134	+ return '';
	3135	+ }
	3136	+ $path = preg_replace( '/[^a-zA-Z0-9._\-\/]/', '', $path );
	3137	+ $path = str_replace( '/', '-', (string) $path );
	3138	+ return trim( (string) $path, '.-' );
	3139	+ }
	3140	+
	3141	+ /**
	3142	+ * The current blog's path as the static tree stores it — real slashes
	3143	+ * preserved, because that tree mirrors the URL
	3144	+ * (`xspeed-static/{host}{request_uri}/index.html`) rather than using a
	3145	+ * single flattened segment. '' for a root blog / single site.
	3146	+ */
	3147	+ public static function site_path_raw(): string {
	3148	+ if ( ! function_exists( 'is_multisite' ) || ! is_multisite() ) {
	3149	+ return '';
	3150	+ }
	3151	+ if ( function_exists( 'is_subdomain_install' ) && is_subdomain_install() ) {
	3152	+ return '';
	3153	+ }
	3154	+ $path = function_exists( 'get_blog_details' ) ? (string) get_blog_details()->path : '/';
	3155	+ $path = trim( str_replace( "\0", '', $path ), '/' );
	3156	+ if ( '' === $path ) {
	3157	+ return '';
	3158	+ }
	3159	+ $path = preg_replace( '#[^a-zA-Z0-9._\-/]#', '', $path );
	3160	+ return trim( (string) $path, '/' );
	3161	+ }
	3162	+
	3163	+ /**
	3164	+ * Static-tree root for the current site: `<host>` plus the blog's real
	3165	+ * path. Mirrors store_static()'s layout so a scoped purge deletes
	3166	+ * exactly this blog's pages.
	3167	+ */
	3168	+ public static function current_static_scope(): string {
	3169	+ // Same switch_to_blog() caveat as current_host_dir() — see current_host().
	3170	+ // Keep the port folded into the segment exactly as store_static() does.
	3171	+ $dir = self::static_host_dir( self::current_host() );
	3172	+ if ( '' === $dir ) {
	3173	+ $dir = 'default';
	3174	+ }
	3175	+ $path = self::site_path_raw();
	3176	+ return '' === $path ? $dir : $dir . '/' . $path;
	3177	+ }
	3178	+
	3179	+ /**
	3180	+ * The bucket for the CURRENT request. Never empty, so an entry is never
	3181	+ * written to the tree root (which is what the unscoped sweeps used to
	3182	+ * delete indiscriminately).
	3183	+ */
	3184	+ public static function current_host_dir(): string {
	3185	+ $host = self::current_host();
	3186	+ return self::site_bucket( $host, self::request_path( '/' ) );
	3187	+ }
	3188	+
	3189	+ /**
	3190	+ * The host the CURRENT blog is served from.
	3191	+ *
	3192	+ * Deliberately NOT just $_SERVER['HTTP_HOST']: inside a
	3193	+ * switch_to_blog() the request header still names whichever site is
	3194	+ * serving the admin screen, while the cache entries we want belong to
	3195	+ * the switched-to blog. On a subdomain network the host IS the bucket,
	3196	+ * so reading the header there would make Pro's per-site "purge this
	3197	+ * site" button clear the network admin's own cache instead — the very
	3198	+ * bug this scoping exists to fix, surviving in one topology.
	3199	+ *
	3200	+ * get_blog_details() follows the switch, so prefer it whenever we are
	3201	+ * on multisite, and fall back to the request header otherwise.
	3202	+ */
	3203	+ public static function current_host(): string {
	3204	+ if ( function_exists( 'is_multisite' ) && is_multisite() && function_exists( 'get_blog_details' ) ) {
	3205	+ $details = get_blog_details();
	3206	+ if ( $details && ! empty( $details->domain ) ) {
	3207	+ return (string) $details->domain;
	3208	+ }
	3209	+ }
	3210	+
	3211	+ if ( isset( $_SERVER['HTTP_HOST'] ) ) {
	3212	+ return sanitize_text_field( wp_unslash( $_SERVER['HTTP_HOST'] ) );
	3213	+ }
	3214	+
	3215	+ /*
	3216	+ * No request header — WP-CLI, or WP-Cron driven by system cron.
	3217	+ *
	3218	+ * Returning '' here made the bucket resolve to the literal `default`
	3219	+ * while HTTP requests were writing to `<host>/`, so a scheduled purge
	3220	+ * swept an empty directory and reported success, and get_stats()
	3221	+ * reported 0 cached pages on a site with a full cache. That is the
	3222	+ * normal setup on any host running DISABLE_WP_CRON, which is most of
	3223	+ * them. Fall back to the site's own registered host. (QA D4 on #166)
	3224	+ */
	3225	+ if ( function_exists( 'home_url' ) ) {
	3226	+ $parts = function_exists( 'wp_parse_url' ) ? wp_parse_url( home_url( '/' ) ) : parse_url( home_url( '/' ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- early-boot fallback only.
	3227	+ if ( is_array( $parts ) && ! empty( $parts['host'] ) ) {
	3228	+ return (string) $parts['host'];
	3229	+ }
	3230	+ }
	3231	+
	3232	+ return '';
	3233	+ }
	3234	+
	3235	+ /**
	3236	+ * Ensure the current site's cache directory exists, with the silence
	3237	+ * index in both it and the shared root. Returns the directory.
	3238	+ */
	3239	+ public static function ensure_host_dir(): string {
	3240	+ $dir = XSPEED_CACHE_DIR . '/' . self::current_host_dir();
	3241	+ if ( ! file_exists( XSPEED_CACHE_DIR ) ) {
	3242	+ wp_mkdir_p( XSPEED_CACHE_DIR );
	3243	+ self::write_silence( XSPEED_CACHE_DIR );
	3244	+ }
	3245	+ if ( ! file_exists( $dir ) ) {
	3246	+ wp_mkdir_p( $dir );
	3247	+ self::write_silence( $dir );
	3248	+ }
	3249	+ return $dir;
	3250	+ }
	3251	+
463	3252	public static function cache_file_for( $key ) {
464		- return XSPEED_CACHE_DIR . '/' . $key . '.html';
	3253	+ return XSPEED_CACHE_DIR . '/' . self::current_host_dir() . '/' . $key . '.html';
465	3254	}
466	3255
467	3256	/**
468	3257	* If a precompressed Brotli sibling (`<file>.br`) exists and the client
		@@ -493,8 +3282,11 @@
493	3282	$br = $file . '.br';
494	3283	if ( ! is_string( $br ) || ! file_exists( $br ) || ! is_readable( $br ) ) {
495	3284	return null;
496	3285	}
	3286	+ if ( ! self::brotli_sibling_is_usable( $file, $br ) ) {
	3287	+ return null; // fall through to the plain .html
	3288	+ }
497	3289	header( 'Content-Encoding: br' );
498	3290	header( 'Vary: Accept-Encoding', false );
499	3291	// The byte length changes for the compressed body — drop any
500	3292	// Content-Length the caller may have set so the stream isn't
		@@ -503,8 +3295,217 @@
503	3295	return $br;
504	3296	}
505	3297
506	3298	/**
	3299	+ * Is a precompressed `.br` sibling safe to serve?
	3300	+ *
	3301	+ * Existence is not enough. The sibling is written with a plain
	3302	+ * file_put_contents() — no atomic rename — so a crash, a full disk, or a
	3303	+ * read that races the write leaves a TRUNCATED file behind. Serving that
	3304	+ * with `Content-Encoding: br` hands the browser a stream it cannot
	3305	+ * inflate: it renders nothing at all (document.body is null) and the
	3306	+ * navigation can hang. A 16-byte .br for a 172KB page reproduces it
	3307	+ * exactly. (#286)
	3308	+ *
	3309	+ * Brotli has no magic number, and no byte-level marker distinguishes a
	3310	+ * truncated stream from a short valid one (the ISLAST bit is bit-packed,
	3311	+ * not byte-aligned). So this checks only what CAN be known by stat:
	3312	+ *
	3313	+ * - Not empty. A zero-byte sibling is unambiguously broken.
	3314	+ * - Not older than the HTML. A stale sibling would serve the PREVIOUS
	3315	+ * revision of the page under the current entry's ETag.
	3316	+ *
	3317	+ * A size-RATIO floor was tried here and removed. Brotli's ratio is
	3318	+ * unbounded on repetitive input: a ~1 MB page of table rows or a product
	3319	+ * grid — the ordinary shape of a big generated page — compresses to
	3320	+ * about 0.04%, so a 2% floor rejected a perfectly good sibling and sent
	3321	+ * visitors the uncompressed page instead, silently. Measured: 963 KB of
	3322	+ * repeated markup → 89 bytes at q5 (0.009%). No floor can separate
	3323	+ * "impossibly small" from "extremely compressible" for arbitrary HTML.
	3324	+ *
	3325	+ * Truncation is prevented at the WRITE side instead — see
	3326	+ * write_atomic(), which the Brotli writer uses so a partial file is
	3327	+ * never visible under the final name. Detection at read time cannot be
	3328	+ * made correct; not creating the bad file can.
	3329	+ *
	3330	+ * Anything suspicious returns false and the caller streams the plain
	3331	+ * .html — slower, always correct. Serving an uninflatable body is worse
	3332	+ * than serving no compression at all.
	3333	+ *
	3334	+ * @param string $file Absolute path to the .html cache file.
	3335	+ * @param string $br Absolute path to its .br sibling.
	3336	+ * @return bool True when the sibling may be served.
	3337	+ */
	3338	+ /**
	3339	+ * Write a cache sidecar so a partial file is never visible.
	3340	+ *
	3341	+ * `file_put_contents()` truncates the target and then fills it, so any
	3342	+ * reader arriving mid-write — or any crash, full disk, or killed worker
	3343	+ * — leaves a SHORT file under the real name. For HTML that degrades to a
	3344	+ * clipped page; for a `.br` sibling it is worse, because a truncated
	3345	+ * brotli stream is not a short page but an UNINFLATABLE one: the browser
	3346	+ * renders nothing at all and the navigation can hang.
	3347	+ *
	3348	+ * Writing to a unique temp file in the same directory and renaming is
	3349	+ * atomic on POSIX, so readers see either the previous complete file or
	3350	+ * the new complete file, never a partial one. This is the half of #286
	3351	+ * that is actually fixable — a read-time heuristic cannot tell a
	3352	+ * truncated brotli stream from a very small valid one, but a truncated
	3353	+ * file that never becomes visible needs no detection.
	3354	+ *
	3355	+ * @param string $path Absolute destination path.
	3356	+ * @param string $contents Bytes to write.
	3357	+ * @return bool True when the destination now holds exactly $contents.
	3358	+ */
	3359	+ public static function write_atomic( string $path, string $contents ): bool {
	3360	+ $dir = dirname( $path );
	3361	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_is_writable -- WP_Filesystem needs admin creds unavailable on a frontend cache write; this is our own cache dir.
	3362	+ if ( ! is_dir( $dir ) || ! is_writable( $dir ) ) {
	3363	+ return false;
	3364	+ }
	3365	+
	3366	+ // Same directory, so the rename stays on one filesystem — a rename
	3367	+ // across devices is a copy and loses atomicity.
	3368	+ $tmp = @tempnam( $dir, '.xspeed-tmp-' ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- a failure returns false and the caller skips the write.
	3369	+ if ( ! is_string( $tmp ) || '' === $tmp ) {
	3370	+ return false;
	3371	+ }
	3372	+
	3373	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- WP_Filesystem needs admin creds unavailable on a frontend cache write; target is our own cache dir.
	3374	+ $written = @file_put_contents( $tmp, $contents ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- handled by the length check below.
	3375	+
	3376	+ // A short write is exactly the failure this function exists to
	3377	+ // prevent, so verify the byte count before publishing the file.
	3378	+ if ( false === $written || $written !== strlen( $contents ) ) {
	3379	+ @unlink( $tmp ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort cleanup of our own temp file; non-fatal.
	3380	+ return false;
	3381	+ }
	3382	+
	3383	+ // tempnam() creates the file 0600; cache files must stay readable by
	3384	+ // the web server, which may run as a different user.
	3385	+ @chmod( $tmp, defined( 'FS_CHMOD_FILE' ) ? FS_CHMOD_FILE : 0644 ); // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod, WordPress.PHP.NoSilencedErrors.Discouraged -- the web server may run as another uid and must be able to read the published file; a chmod failure is not fatal.
	3386	+
	3387	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.rename_rename, WordPress.PHP.NoSilencedErrors.Discouraged -- the atomic publish this function exists for; WP_Filesystem offers no atomic rename and needs admin creds.
	3388	+ if ( ! @rename( $tmp, $path ) ) {
	3389	+ @unlink( $tmp ); // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort cleanup; non-fatal.
	3390	+ return false;
	3391	+ }
	3392	+
	3393	+ return true;
	3394	+ }
	3395	+
	3396	+ public static function brotli_sibling_is_usable( string $file, string $br ): bool {
	3397	+ $br_size = (int) @filesize( $br ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- a stat failure means "don't serve it", handled by the <= 0 check.
	3398	+ if ( $br_size <= 0 ) {
	3399	+ return false;
	3400	+ }
	3401	+
	3402	+ $html_size = (int) @filesize( $file ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- as above.
	3403	+ if ( $html_size <= 0 ) {
	3404	+ return false;
	3405	+ }
	3406	+
	3407	+ // A sibling older than the page it compresses is stale.
	3408	+ $br_mtime = (int) @filemtime( $br ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- as above.
	3409	+ $html_mtime = (int) @filemtime( $file ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- as above.
	3410	+ if ( $br_mtime > 0 && $html_mtime > 0 && $br_mtime < $html_mtime ) {
	3411	+ return false;
	3412	+ }
	3413	+
	3414	+ // The writer recorded how many bytes it produced. Where that record
	3415	+ // exists, truncation is a certainty rather than an inference: a
	3416	+ // stream shorter than its own declared length cannot inflate, and
	3417	+ // one that matches was published whole. This is what a size ratio
	3418	+ // could never be — brotli's ratio is unbounded on repetitive input,
	3419	+ // so a 0.01% sibling of a generated page is genuinely valid.
	3420	+ //
	3421	+ // Absent for a sibling written before this version, or by an add-on
	3422	+ // that writes the file directly. That case keeps the checks above
	3423	+ // and no more, which is where a pre-existing truncated file on a
	3424	+ // live site still slips through — write_atomic() stops NEW ones,
	3425	+ // but it cannot retroactively vouch for what is already on disk.
	3426	+ $expected = self::brotli_expected_size( $br );
	3427	+ if ( $expected > 0 && $br_size !== $expected ) {
	3428	+ return false;
	3429	+ }
	3430	+
	3431	+ return true;
	3432	+ }
	3433	+
	3434	+ /**
	3435	+ * Path of the sidecar recording a `.br` sibling's complete byte count.
	3436	+ *
	3437	+ * Kept beside the sibling as `<file>.html.br.size` rather than folded
	3438	+ * into the entry's `.meta`: the static tree the web server serves has no
	3439	+ * `.meta` at all, and the two trees must answer this question the same
	3440	+ * way. Every path that deletes a `.br` deletes this with it.
	3441	+ *
	3442	+ * @param string $br Absolute path to the `.br` sibling.
	3443	+ * @return string Absolute path to its size sidecar.
	3444	+ */
	3445	+ public static function brotli_size_sidecar( string $br ): string {
	3446	+ return $br . '.size';
	3447	+ }
	3448	+
	3449	+ /**
	3450	+ * The byte count the writer recorded for a `.br` sibling, or 0 when no
	3451	+ * record exists (a sibling predating this version, or written by an
	3452	+ * add-on that bypassed write_brotli_sibling()).
	3453	+ *
	3454	+ * @param string $br Absolute path to the `.br` sibling.
	3455	+ * @return int Expected size in bytes, or 0 when unknown.
	3456	+ */
	3457	+ public static function brotli_expected_size( string $br ): int {
	3458	+ $sidecar = self::brotli_size_sidecar( $br );
	3459	+ if ( ! is_file( $sidecar ) ) {
	3460	+ return 0;
	3461	+ }
	3462	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- our own cache dir; WP_Filesystem needs admin creds unavailable on a frontend HIT.
	3463	+ $raw = @file_get_contents( $sidecar ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- an unreadable sidecar means "unknown", handled by the cast below.
	3464	+ return max( 0, (int) trim( (string) $raw ) );
	3465	+ }
	3466	+
	3467	+ /**
	3468	+ * Publish a `.br` sibling together with the record of its own length.
	3469	+ *
	3470	+ * The single writer every producer of a `.br` should route through — the
	3471	+ * Pro Brotli module included. Publishing the body atomically stops a
	3472	+ * truncated file from ever becoming visible; recording the byte count
	3473	+ * lets the serve path prove wholeness for the files that already exist
	3474	+ * on disk when this ships.
	3475	+ *
	3476	+ * Order matters: the size sidecar is removed first and written last, so
	3477	+ * a reader arriving mid-update sees "no record" (checks above still
	3478	+ * apply) rather than the previous body's length against the new body.
	3479	+ *
	3480	+ * @param string $br Absolute path to the `.br` sibling to write.
	3481	+ * @param string $contents Compressed bytes.
	3482	+ * @return bool True when both the sibling and its size record are in place.
	3483	+ */
	3484	+ public static function write_brotli_sibling( string $br, string $contents ): bool {
	3485	+ $sidecar = self::brotli_size_sidecar( $br );
	3486	+ if ( is_file( $sidecar ) ) {
	3487	+ wp_delete_file( $sidecar );
	3488	+ }
	3489	+
	3490	+ if ( ! self::write_atomic( $br, $contents ) ) {
	3491	+ return false;
	3492	+ }
	3493	+
	3494	+ if ( self::write_atomic( $sidecar, (string) strlen( $contents ) ) ) {
	3495	+ return true;
	3496	+ }
	3497	+
	3498	+ // The body landed but its length did not. That sibling is servable
	3499	+ // and unguarded — exactly the file this function exists to prevent —
	3500	+ // and the caller has no way to know. Withdraw it: a MISS costs one
	3501	+ // uncompressed response, where an unguarded sibling can cost a blank
	3502	+ // page for as long as the entry lives.
	3503	+ wp_delete_file( $br );
	3504	+ return false;
	3505	+ }
	3506	+
	3507	+ /**
507	3508	* Sidecar metadata file for a cache entry. Holds response bits the HIT
508	3509	* path must replay — Content-Type (cached feeds → application/rss+xml,
509	3510	* sitemaps → text/xml) and status (a cached 404 must serve 404, not
510	3511	* 200). JSON, one tiny file per entry, written only when there's
		@@ -510,17 +3511,19 @@
510	3511	* 200). JSON, one tiny file per entry, written only when there's
511	3512	* something non-default to replay.
512	3513	*/
513	3514	public static function cache_meta_for( $key ) {
514		- return XSPEED_CACHE_DIR . '/' . $key . '.meta';
	3515	+ return XSPEED_CACHE_DIR . '/' . self::current_host_dir() . '/' . $key . '.meta';
515	3516	}
516	3517
517	3518	/**
518	3519	* Read the .meta sidecar for a cache entry as an array, or [] if none.
519		- * Keys: 'content_type' (string), 'status' (int). Used on the HIT path
520		- * to replay them before streaming the file.
	3520	+ * Keys: 'content_type' (string), 'status' (int), 'ttl' (int seconds).
	3521	+ * Used on the HIT path to replay content-type/status before streaming
	3522	+ * the file, and by Cache_GC to age an entry by its own TTL rather than
	3523	+ * the global one — hence public.
521	3524	*/
522		- private static function read_meta( $key ): array {
	3525	+ public static function read_meta( $key ): array {
523	3526	$meta_file = self::cache_meta_for( $key );
524	3527	if ( ! file_exists( $meta_file ) ) {
525	3528	return array();
526	3529	}
		@@ -537,8 +3540,19 @@
537	3540	* and returns true (caller should exit without a body). Returns false to
538	3541	* proceed with a normal 200 body. Lets aggregators/browsers skip
539	3542	* re-downloading an unchanged cached response. (FBS-82407 #5)
540	3543	*
	3544	+ * Also stamps `X-XSpeed-Built` from the same mtime. This is the PHP serve
	3545	+ * path's build time, and the only place on it that holds the file: mark()
	3546	+ * has already run by the time we get here and resolved the edge-header
	3547	+ * filter without one. Both are emitted, and a purge verifier prefers the
	3548	+ * stamp: `Last-Modified` carries the same integer, but it is a generic
	3549	+ * header that the origin-side cache layer such a verifier exists to
	3550	+ * detect — or any proxy in between — may rewrite to its own store time,
	3551	+ * which would turn a stale origin into a pass. Nothing but xSpeed's own
	3552	+ * serve code writes `X-XSpeed-Built`, so a value older than the purge is
	3553	+ * proof the origin answered with old HTML.
	3554	+ *
541	3555	* @param string $file Absolute path to the cache .html file.
542	3556	* @return bool True when a 304 was sent.
543	3557	*/
544	3558	public static function serve_not_modified( string $file ): bool {
		@@ -549,8 +3563,12 @@
549	3563	$last_modified = gmdate( 'D, d M Y H:i:s', $mtime ) . ' GMT';
550	3564	$etag = '"' . md5( $file . '|' . $mtime ) . '"';
551	3565	header( 'Last-Modified: ' . $last_modified );
552	3566	header( 'ETag: ' . $etag );
	3567	+ // Before the 304 branch below, so a conditional request that gets a
	3568	+ // bodyless 304 still carries the stamp. A verifier's fetch may well
	3569	+ // be conditional, and a 304 with no build time reads as unverifiable.
	3570	+ header( self::BUILT_HEADER . ': ' . $mtime );
553	3571
554	3572	$ims = isset( $_SERVER['HTTP_IF_MODIFIED_SINCE'] ) ? trim( sanitize_text_field( wp_unslash( $_SERVER['HTTP_IF_MODIFIED_SINCE'] ) ) ) : '';
555	3573	$inm = isset( $_SERVER['HTTP_IF_NONE_MATCH'] ) ? trim( sanitize_text_field( wp_unslash( $_SERVER['HTTP_IF_NONE_MATCH'] ) ) ) : '';
556	3574
		@@ -586,9 +3604,45 @@
586	3604	* @param int $max_age Computed max-age in seconds.
587	3605	*/
588	3606	$max_age = (int) apply_filters( 'xspeed_cache_max_age', $max_age );
589	3607
590		- return ( time() - filemtime( $file ) ) > $max_age;
	3608	+ // Honour the per-entry TTL the .meta sidecar carries, when it is
	3609	+ // SHORTER than what we just resolved. The sidecar records the TTL
	3610	+ // this specific entry was written under — a nonce cap (#236), a Pro
	3611	+ // feed/404 expiry — and the drop-in already reads it. is_expired()
	3612	+ // did not, so on the engine path a capped entry was still served for
	3613	+ // the full configured lifetime: exactly the stale nonce the cap
	3614	+ // exists to prevent. Only ever shortens, so an entry can never be
	3615	+ // kept alive past the configured maximum by a stale sidecar.
	3616	+ // Derive the sidecar from the FILE we were handed rather than
	3617	+ // recomputing cache_key(): callers legitimately ask about an entry
	3618	+ // that isn't the current request's (Cache_GC sweeps, Pro's warmer),
	3619	+ // and cache_key() would answer for the wrong one — besides needing a
	3620	+ // request context this function has no business requiring.
	3621	+ $meta_file = preg_replace( '/\.html$/', '.meta', (string) $file );
	3622	+ if ( is_string( $meta_file ) && $meta_file !== $file && is_readable( $meta_file ) ) {
	3623	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- our own cache dir; WP_Filesystem needs admin creds unavailable on a frontend read.
	3624	+ $raw = file_get_contents( $meta_file );
	3625	+ $decoded = is_string( $raw ) ? json_decode( $raw, true ) : null;
	3626	+ if ( is_array( $decoded ) && isset( $decoded['ttl'] ) ) {
	3627	+ $entry_ttl = (int) $decoded['ttl'];
	3628	+ if ( $entry_ttl > 0 && ( $max_age < 1 || $entry_ttl < $max_age ) ) {
	3629	+ $max_age = $entry_ttl;
	3630	+ }
	3631	+ }
	3632	+ }
	3633	+
	3634	+ // A missing file is "expired" — the caller should re-render. Guard
	3635	+ // filemtime() rather than letting it warn: callers legitimately ask
	3636	+ // about a file that isn't there (Pro's predictive warmer probes for
	3637	+ // freshness, and Cache_GC can collect an entry between the check and
	3638	+ // the read), and on a site with WP_DEBUG the warning is noise.
	3639	+ $mtime = file_exists( $file ) ? filemtime( $file ) : false;
	3640	+ if ( false === $mtime ) {
	3641	+ return true;
	3642	+ }
	3643	+
	3644	+ return ( time() - (int) $mtime ) > $max_age;
591	3645	}
592	3646
593	3647	/**
594	3648	* Accumulator for the full response body across all output-handler phases.
		@@ -619,8 +3673,13 @@
619	3673
620	3674	$full = self::$accumulated;
621	3675	self::$accumulated = '';
622	3676
	3677	+ // Consumed here, on every final path, so a later call can never
	3678	+ // compare against this request's snapshot.
	3679	+ $asset_stamp = self::$asset_stamp_at_open;
	3680	+ self::$asset_stamp_at_open = null;
	3681	+
623	3682	if ( strlen( $full ) < 255 ) {
624	3683	return $buffer;
625	3684	}
626	3685
		@@ -642,8 +3701,40 @@
642	3701	// the first visitor sees unminified HTML, every cache hit after that
643	3702	// is minified.
644	3703	$single_chunk = ( $buffer === $full );
645	3704
	3705	+ /**
	3706	+ * Filter: xspeed_cache_final_html
	3707	+ *
	3708	+ * Last chance to transform the fully-rendered page HTML before it is
	3709	+ * minified and written to the cache file. Runs on cache MISS only, so
	3710	+ * whatever a listener injects here is baked into the cached HTML and
	3711	+ * replayed on every subsequent HIT (the drop-in short-circuits before
	3712	+ * PHP on a HIT — a wp_head hook would never fire there).
	3713	+ *
	3714	+ * The Preload module uses this to inject the LCP-image <link rel=preload>
	3715	+ * + preconnect hints and add fetchpriority="high" to the hero <img>.
	3716	+ * Keep listeners fast and idempotent; this is the on-wire body.
	3717	+ *
	3718	+ * A result with fewer than 255 non-whitespace bytes is treated as a
	3719	+ * failed listener and replaced by the rendered page.
	3720	+ *
	3721	+ * @param string $full Complete page HTML.
	3722	+ */
	3723	+ $rendered = $full;
	3724	+ $full = apply_filters( 'xspeed_cache_final_html', $full );
	3725	+
	3726	+ // A listener whose preg_* call fails returns null, which a cast turns
	3727	+ // into ''. That empty string used to be signed, sent and cached, and
	3728	+ // nginx then served the signature comment as a HIT to every visitor
	3729	+ // until purge. Same floor as the rendered page above. (#723)
	3730	+ if ( ! is_string( $full ) || strlen( trim( $full ) ) < 255 ) {
	3731	+ $full = $rendered;
	3732	+ }
	3733	+ if ( $single_chunk ) {
	3734	+ $buffer = $full;
	3735	+ }
	3736	+
646	3737	// minify_html now owned by the Minify module; read through the
647	3738	// module's storage so this stays consistent with the engine that
648	3739	// applies CSS/JS minification.
649	3740	$minify_opts = Settings_Manager::get( 'minify' );
		@@ -653,27 +3744,129 @@
653	3744	$buffer = $full;
654	3745	}
655	3746	}
656	3747
657		- if ( ! file_exists( XSPEED_CACHE_DIR ) ) {
658		- wp_mkdir_p( XSPEED_CACHE_DIR );
659		- self::write_silence( XSPEED_CACHE_DIR );
	3748	+ // AFTER minification on purpose — the HTML minifier strips comments,
	3749	+ // so signing earlier would erase the signature from every minified
	3750	+ // page. Baked into the cached bytes so all three serve paths (nginx
	3751	+ // static rewrite, .htaccess, the PHP drop-in) carry it identically.
	3752	+ $full = self::signed( $full );
	3753	+ if ( $single_chunk ) {
	3754	+ $buffer = $full;
660	3755	}
661	3756
662		- // Path safety: cache_file_for() builds `XSPEED_CACHE_DIR . '/' . $key . '.html'`
663		- // where $key comes from md5() — guaranteed to be exactly 32 lowercase
664		- // hex chars, so no traversal sequence ('..', '/', null byte, etc.)
665		- // can appear. The write is therefore always inside XSPEED_CACHE_DIR.
666		- $key = self::cache_key();
	3757	+ // Per-site directory — see ensure_host_dir(). (#6)
	3758	+ self::ensure_host_dir();
	3759	+
	3760	+ // Path safety: cache_file_for() builds
	3761	+ // `XSPEED_CACHE_DIR . '/' . <host> . '/' . $key . '.html'` where $key
	3762	+ // comes from md5() — guaranteed to be exactly 32 lowercase hex chars —
	3763	+ // and <host> is filtered by host_dir() to [A-Za-z0-9.-] with leading
	3764	+ // dots trimmed, so no traversal sequence ('..', '/', null byte, etc.)
	3765	+ // can appear in either segment. The write is therefore always inside
	3766	+ // XSPEED_CACHE_DIR.
	3767	+ $key = self::cache_key();
	3768	+
	3769	+ // Query-string gate. should_cache() waved this request through
	3770	+ // because every param is on the ignored_query_params allow-list, and
	3771	+ // cache_key() drops the query so reads share the canonical entry.
	3772	+ // That sharing is safe on READ but not on WRITE: this response was
	3773	+ // rendered WITH the params, and WordPress reflects REQUEST_URI into
	3774	+ // form actions, share links and plugin smart tags — so storing it
	3775	+ // would serve an attacker-chosen variant under the clean URL for the
	3776	+ // whole TTL (#241).
	3777	+ //
	3778	+ // This sits BELOW the transforms deliberately. Returning above them
	3779	+ // also skipped xspeed_cache_final_html, and every listener disables
	3780	+ // its own fallback ob_start() when the page cache is on precisely
	3781	+ // because that filter is the shared transport — so a visitor
	3782	+ // arriving on ?utm_source=… was served HTML with no LCP preload, no
	3783	+ // preconnect, no CDN rewrite, no CSS combine and no HTML minify.
	3784	+ // That is the ad-click and newsletter cohort getting the least
	3785	+ // optimised page on the site. Only the WRITE is skipped, which is
	3786	+ // what this fix was always meant to do — and it is where the
	3787	+ // deferred writer has always placed its own copy of the guard.
	3788	+ if ( self::query_string_blocks_write() ) {
	3789	+ return $buffer;
	3790	+ }
	3791	+
	3792	+ // A purge deleted minified or combined files while this page was
	3793	+ // rendering, so it may link names that are gone. Serve it, but do
	3794	+ // not store it; the next request renders against the files as they
	3795	+ // are now.
	3796	+ if ( self::assets_purged_since( $asset_stamp ) ) {
	3797	+ return $buffer;
	3798	+ }
667	3799	$file = self::cache_file_for( $key );
	3800	+
	3801	+ // A render-time translation plugin (TranslatePress) wraps our buffer,
	3802	+ // so the bytes we hold here are still UNTRANSLATED — its callback has
	3803	+ // not run yet, and writing now would cache English under a French URL
	3804	+ // and bake in its internal #TRPLINKPROCESSED markers. Hand off to
	3805	+ // shutdown, where the outer buffer has already translated, and let
	3806	+ // the pass-through below deliver this request untouched.
	3807	+ if ( self::translation_plugin_active() ) {
	3808	+ self::$deferred_key = $key;
	3809	+ self::$deferred_asset_stamp = $asset_stamp;
	3810	+ // Reaching here means finalize_buffer() ran to completion: the
	3811	+ // status gate passed, should_cache() said yes, and PHP handed us
	3812	+ // the whole buffer. A wp_die() or exit() mid-render unwinds the
	3813	+ // buffer stack WITHOUT calling this callback, so the flag stays
	3814	+ // false and the shutdown writer declines — see the guard there.
	3815	+ self::$render_completed = true;
	3816	+ // A PHP shutdown function, not a WP `shutdown` action: this must
	3817	+ // run after the output-buffer stack has unwound, and WP's
	3818	+ // shutdown action fires while our outer buffer is still open.
	3819	+ register_shutdown_function( array( __CLASS__, 'write_deferred_translated_cache' ) );
	3820	+ return $buffer;
	3821	+ }
	3822	+
668	3823	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- WP_Filesystem requires admin context for credentials; cache writes happen on frontend requests where it's unavailable.
669		- file_put_contents( $file, $full, LOCK_EX );
	3824	+ $stored = file_put_contents( $file, $full, LOCK_EX );
670	3825
	3826	+ /*
	3827	+ * No edge headers on a MISS. Not even a stored one.
	3828	+ *
	3829	+ * A MISS is the FIRST render, and it is the render most likely to be
	3830	+ * replaced: critical CSS and unused CSS are generated after the fact
	3831	+ * and applied to later requests, so the copy written here is the
	3832	+ * pre-optimization one. Telling a CDN to hold it pins exactly the
	3833	+ * version xSpeed is about to improve on — reported from a live site,
	3834	+ * where Cloudflare had cached an unoptimized first render.
	3835	+ *
	3836	+ * `CDN-Cache-Control` is why it reaches the edge at all: Cloudflare
	3837	+ * honours it as the CDN-targeted directive whatever its own cache
	3838	+ * rules say, so an origin header is enough to pin HTML for the whole
	3839	+ * TTL even where edge page caching is switched off.
	3840	+ *
	3841	+ * A HIT is the safe moment and the honest one: it means xSpeed is
	3842	+ * serving its stored copy, that copy is what the edge would mirror,
	3843	+ * and a later regeneration purges it — which reaches the edge through
	3844	+ * the purge actions. So the edge caches from the second visitor on,
	3845	+ * one render later than before and the right one.
	3846	+ */
	3847	+
	3848	+ /**
	3849	+ * Fires after the flat hash cache file ({md5}.html) is written.
	3850	+ *
	3851	+ * Mirror of `xspeed_static_file_written` for the flat cache. The PHP
	3852	+ * serve path (Cache::maybe_serve_brotli / the drop-in) serves THIS
	3853	+ * file and looks for a `{md5}.html.br` sibling — which only the Pro
	3854	+ * Brotli listener on this hook writes. Without it the .br sibling was
	3855	+ * never created and the PHP path could never serve Brotli (FBS-83039,
	3856	+ * Blocker 2): the static-tree .br (written on xspeed_static_file_written)
	3857	+ * lives in a different cache layout the PHP path never reads.
	3858	+ *
	3859	+ * @param string $file Absolute path to the flat cache file just written.
	3860	+ * @param string $full The HTML written to it.
	3861	+ */
	3862	+ do_action( 'xspeed_flat_file_written', $file, $full );
	3863	+
671	3864	// Persist a non-default Content-Type so the HIT path can replay it
672	3865	// (cached feeds must serve application/rss+xml, not text/html).
673	3866	// Only written when the response set a content-type other than
674	3867	// the HTML default — pages don't pay for an extra file.
675		- self::write_meta( $key );
	3868	+ self::write_meta( $key, $full );
676	3869
677	3870	// Static-cache tree (xspeed-static/{host}{path}/index.html). The
678	3871	// .htaccess rewrite block serves this file directly via the web
679	3872	// server, bypassing PHP for ~3-5× lower TTFB vs the drop-in path.
		@@ -688,9 +3881,16 @@
688	3881	// 200, FBS-82406) or a non-HTML content-type (a cached feed would go
689	3882	// out as text/html, FBS-82407). The web server serves these .html files
690	3883	// directly with no PHP, so there's no .meta replay — keep them on the
691	3884	// drop-in / PHP path instead, which DOES replay status + content-type.
692		- if ( self::static_rewrite_allowed() && self::response_is_plain_html() ) {
	3885	+ // The static tree cannot replay a sidecar. A file served straight by
	3886	+ // the web server carries the headers baked into the rule that serves
	3887	+ // the whole site — the very answer this entry exists because it
	3888	+ // disagreed with. Same reasoning as the status and content-type
	3889	+ // cases: what the fast path cannot replay belongs on the drop-in path.
	3890	+ if ( self::static_rewrite_allowed()
	3891	+ && self::response_is_plain_html()
	3892	+ && array() === self::per_entry_edge_headers() ) {
693	3893	self::store_static( $full );
694	3894	}
695	3895
696	3896	return $buffer;
		@@ -702,30 +3902,170 @@
702	3902	* rewrite block points at this path so cache hits skip PHP
703	3903	* entirely. Caller already minified/finalized $html.
704	3904	*
705	3905	* Path safety: $host is restricted to a `[a-zA-Z0-9.\-]` allowlist;
706		- * $uri has its query string stripped, null bytes removed, '..'
707		- * sequences collapsed, and after concatenation we verify the
708		- * resolved real path stays inside XSPEED_CACHE_STATIC_DIR before
709		- * any write. Anything off the happy path returns silently.
	3906	+ * the path goes through static_path(), which decodes it the way the
	3907	+ * web server will and refuses anything that could leave the host
	3908	+ * directory or share a file with another page. After the directory is
	3909	+ * created we verify its real path is inside XSPEED_CACHE_STATIC_DIR
	3910	+ * before any write. Anything off the happy path returns silently.
	3911	+ *
	3912	+ * INVARIANT — the static tree is keyed by `{host}{path}` and NOTHING
	3913	+ * else, and both generated rewrites refuse any request that carries a
	3914	+ * query string at all (`RewriteCond %{QUERY_STRING} ^$` on Apache,
	3915	+ * `if ($args)` in nginx_snippet()). So a response may only be stored
	3916	+ * here when cache_key() adds no discriminator beyond `{host}{path}`:
	3917	+ * a query-keyed entry can never be *served* from here, only mis-served
	3918	+ * as the bare path. Any future opt-in that folds a query param into the
	3919	+ * key needs a guard below, exactly like the search one.
710	3920	*/
	3921	+ /**
	3922	+ * Transient holding the most recent static-tree refusal.
	3923	+ *
	3924	+ * Short-lived on purpose: it describes what the last cacheable render
	3925	+ * actually did, so a stale entry would keep warning about a page whose
	3926	+ * nonces have since been removed. A site that still refuses simply
	3927	+ * rewrites it on the next render. (#372)
	3928	+ */
	3929	+ private const STATIC_SKIP_TRANSIENT = 'xspeed_static_skip';
	3930	+
	3931	+ /**
	3932	+ * File beside a static index.html that holds its nonce deadline. GC reads
	3933	+ * it; every path that deletes the page must delete it too, or the folder
	3934	+ * can never be removed.
	3935	+ */
	3936	+ public const EXPIRES_MARKER = '.xspeed-expires';
	3937	+
	3938	+ /**
	3939	+ * Remember why a page was kept out of the static tree, for Health.
	3940	+ *
	3941	+ * Records the URL, the reason, and — for the nonce case — the distinct
	3942	+ * nonce KEYS found, which is what makes the finding actionable: the names
	3943	+ * (`eael_login_nonce`, `post_grid_pagination_nonce`, …) trace straight back
	3944	+ * to the plugin emitting them, and it is usually a widget the site does not
	3945	+ * use on that page. Only key names are kept, never the nonce values.
	3946	+ *
	3947	+ * @param string $reason Machine-readable refusal reason.
	3948	+ * @param string $html The response, for extracting the nonce keys.
	3949	+ */
	3950	+ private static function note_static_skip( string $reason, string $html = '' ): void {
	3951	+ if ( ! function_exists( 'set_transient' ) ) {
	3952	+ return;
	3953	+ }
	3954	+
	3955	+ $keys = array();
	3956	+ if ( 'nonce' === $reason && '' !== $html ) {
	3957	+ // Must recognise the SAME shapes response_has_nonce() refuses on,
	3958	+ // or a page is skipped and reported with no keys at all — which is
	3959	+ // most of them, since the plain `name="_wpnonce"` form field is the
	3960	+ // commonest shape by far and only the JSON one was handled here.
	3961	+ // The keys are the actionable half of the message, so a mismatch
	3962	+ // leaves the admin with bad news and nothing to act on.
	3963	+ //
	3964	+ // Both alternations capture the KEY only: each value pattern sits
	3965	+ // outside the capture group, so a nonce secret can never be stored.
	3966	+ $found = array();
	3967	+ if ( preg_match_all( '/name=["\']([a-z0-9_\-\[\]]*nonce[a-z0-9_\-\[\]]*)["\']/i', $html, $m ) ) {
	3968	+ $found = array_merge( $found, $m[1] );
	3969	+ }
	3970	+ if ( preg_match_all( '/["\']([a-z0-9_\-]*nonce[a-z0-9_\-]*)["\']\s*:\s*["\'][a-f0-9]{8,}["\']/i', $html, $m ) ) {
	3971	+ $found = array_merge( $found, $m[1] );
	3972	+ }
	3973	+ // The query-arg shape (`?_wpnonce=…`) has no key name to report
	3974	+ // beyond the literal, so name it explicitly rather than reporting
	3975	+ // nothing for a page that was genuinely refused.
	3976	+ if ( preg_match( '/[?&]_wpnonce=/i', $html ) ) {
	3977	+ $found[] = '_wpnonce';
	3978	+ }
	3979	+ $keys = array_slice( array_values( array_unique( $found ) ), 0, 10 );
	3980	+ }
	3981	+
	3982	+ set_transient(
	3983	+ self::STATIC_SKIP_TRANSIENT,
	3984	+ array(
	3985	+ 'reason' => $reason,
	3986	+ 'url' => esc_url_raw( self::request_path() ),
	3987	+ 'keys' => $keys,
	3988	+ 'at' => time(),
	3989	+ ),
	3990	+ HOUR_IN_SECONDS
	3991	+ );
	3992	+ }
	3993	+
	3994	+ /**
	3995	+ * The most recent static-tree refusal, or an empty array when there is none.
	3996	+ *
	3997	+ * @return array{reason:string,url:string,keys:string[],at:int}|array{}
	3998	+ */
	3999	+ public static function last_static_skip(): array {
	4000	+ $stored = function_exists( 'get_transient' ) ? get_transient( self::STATIC_SKIP_TRANSIENT ) : false;
	4001	+ return is_array( $stored ) && ! empty( $stored['reason'] ) ? $stored : array();
	4002	+ }
	4003	+
711	4004	private static function store_static( string $html ): void {
	4005	+ // Search results are keyed by term in cache_key() (`|s=<term>`) but
	4006	+ // carry the *path* of whatever URL was searched from — for the usual
	4007	+ // `/?s=<term>` that path is `/`. Writing them here would file the
	4008	+ // results page as `{host}/index.html` and the web server would serve
	4009	+ // it to every visitor as the homepage: an unauthenticated visitor
	4010	+ // poisons the front page with one request. Searches stay on the
	4011	+ // drop-in, which replays the term-keyed entry correctly. (#191)
	4012	+ //
	4013	+ // This is a superset of the query-string check the exclusion gate
	4014	+ // does: it also covers `/?%73=<term>`, which decodes to the same
	4015	+ // search (the shape #109 fixed on the gate side).
	4016	+ if ( self::should_cache_search() ) {
	4017	+ return;
	4018	+ }
	4019	+
	4020	+ // Same hazard for the allow-listed query params: store_static()
	4021	+ // strips the query and files the response under the bare path, which
	4022	+ // the web server then serves to every visitor of the clean URL with
	4023	+ // no PHP involved at all — so none of the engine's checks can catch
	4024	+ // it later (#241). The callers already gate on this, but the guard
	4025	+ // is repeated here because this tree is the most dangerous of the
	4026	+ // three write sites and must not depend on its callers.
	4027	+ if ( self::request_has_query_string() ) {
	4028	+ return;
	4029	+ }
	4030	+
	4031	+ // A nonce-bearing page is served here with NO PHP: no TTL check and
	4032	+ // no .meta replay, so the per-entry cap that keeps the drop-in honest
	4033	+ // (#236) cannot reach a file once it is written. Only Cache_GC removes
	4034	+ // it, and until it does the page hands every visitor the same nonce —
	4035	+ // which, once that nonce dies, breaks every anonymous form on it.
	4036	+ //
	4037	+ // Refusing outright was the safe answer, and it cost every
	4038	+ // nonce-bearing page the static tree entirely: a site whose homepage
	4039	+ // carries one unused login nonce ran PHP on every request forever.
	4040	+ // The nonce's own remaining life is the better gate — the page is
	4041	+ // written and its deadline recorded below for GC to enforce.
	4042	+ //
	4043	+ // A nonce we cannot put a clock on is still refused, and that refusal
	4044	+ // is still recorded: it stays completely silent otherwise, because the
	4045	+ // drop-in answers HIT while Health reports the fast path active from a
	4046	+ // probe that writes its OWN file and never proves real pages reach the
	4047	+ // tree. (#372)
	4048	+ $nonce_ttl = self::response_has_nonce( $html ) ? self::nonce_capped_ttl( $html, 0 ) : 0;
	4049	+ if ( self::response_has_nonce( $html ) && $nonce_ttl < 1 ) {
	4050	+ self::note_static_skip( 'nonce', $html );
	4051	+ return;
	4052	+ }
	4053	+
712	4054	$host = isset( $_SERVER['HTTP_HOST'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_HOST'] ) ) : '';
713		- $uri = isset( $_SERVER['REQUEST_URI'] ) ? sanitize_text_field( wp_unslash( $_SERVER['REQUEST_URI'] ) ) : '';
714		- $host = preg_replace( '/[^a-zA-Z0-9.\-]/', '', $host );
715		- $uri = str_replace( "\0", '', $uri );
716		- $uri = (string) strtok( $uri, '?' );
	4055	+ $host = self::static_host_dir( $host );
	4056	+ $uri = self::request_path();
717	4057	if ( '' === $host || '' === $uri ) {
718	4058	return;
719	4059	}
720		- // Collapse any traversal sequences before path resolution.
721		- $uri = preg_replace( '#/+#', '/', $uri );
722		- if ( false !== strpos( $uri, '..' ) ) {
	4060	+ // Decoded the way the web server will decode it, or refused.
	4061	+ $rel = self::static_path( $uri );
	4062	+ if ( null === $rel ) {
723	4063	return;
724	4064	}
725	4065
726	4066	$base = rtrim( XSPEED_CACHE_STATIC_DIR, '/' );
727		- $dir = $base . '/' . $host . rtrim( $uri, '/' );
	4067	+ $dir = $base . '/' . $host . $rel;
728	4068	$file = $dir . '/index.html';
729	4069
730	4070	// Resolve the parent against the cache root to be sure the
731	4071	// final path is inside our tree even if the OS does anything
		@@ -740,11 +4080,28 @@
740	4080	}
741	4081	if ( ! is_dir( $dir ) ) {
742	4082	return;
743	4083	}
	4084	+ // static_path() already refuses every traversal spelling. This
	4085	+ // catches a directory in the tree that resolves somewhere else.
	4086	+ $dir_real = realpath( $dir );
	4087	+ $static_real = realpath( $base );
	4088	+ if ( false === $dir_real || false === $static_real || 0 !== strpos( $dir_real . '/', $static_real . '/' ) ) {
	4089	+ return;
	4090	+ }
744	4091	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- Same rationale as the flat-hash cache write above: WP_Filesystem isn't available on frontend requests, and the cache write must happen during shutdown.
745	4092	$written = file_put_contents( $file, $html, LOCK_EX );
746	4093
	4094	+ // A nonce-bearing page expires on the nonce's schedule, not the site's.
	4095	+ // Nothing reads this file at serve time — the web server hands over
	4096	+ // index.html without PHP — so the deadline is recorded beside it for
	4097	+ // GC, which is the only thing that can enforce it. Written before the
	4098	+ // action below so a listener that shells out cannot race the sweep.
	4099	+ if ( false !== $written && $nonce_ttl > 0 ) {
	4100	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- same rationale as the write above.
	4101	+ file_put_contents( $dir . '/' . self::EXPIRES_MARKER, (string) ( time() + $nonce_ttl ), LOCK_EX );
	4102	+ }
	4103	+
747	4104	if ( false !== $written ) {
748	4105	/**
749	4106	* Fires after a static cache file (index.html) is written.
750	4107	*
		@@ -796,9 +4153,236 @@
796	4153	}
797	4154	return true;
798	4155	}
799	4156
800		- private static function write_meta( string $key ): void {
	4157	+ /**
	4158	+ * Append the cache signature comment to a finished page.
	4159	+ *
	4160	+ * The plugin's one outward version signal: external scanners (the
	4161	+ * xspeedcache.com speed test among them) read it to detect xSpeed and
	4162	+ * its version on a cached page, the way other cache plugins sign their
	4163	+ * output. Callers apply it AFTER HTML minification — the minifier strips
	4164	+ * comments — and before every cache write, so all serve paths carry the
	4165	+ * same bytes.
	4166	+ *
	4167	+ * The generation time is baked in here, at write time, in UTC. It is the
	4168	+ * moment the cached bytes were produced — NOT the moment they were served
	4169	+ * — because all three serve paths replay the same stored file, and two of
	4170	+ * them (the nginx/`.htaccess` static rewrite) run no PHP at all and so
	4171	+ * could never stamp a serve-time value. Reading the age of a page is the
	4172	+ * point: `generated` plus the current clock tells you how stale it is.
	4173	+ * `gmdate()` (not `current_time()`) keeps the value comparable across
	4174	+ * sites regardless of the configured timezone.
	4175	+ *
	4176	+ * @param string $html Finished page HTML.
	4177	+ * @return string HTML with the signature appended (or unchanged when a
	4178	+ * filter removed it).
	4179	+ */
	4180	+ private static function signed( string $html ): string {
	4181	+ $version = defined( 'XSPEED_VERSION' ) ? XSPEED_VERSION : '';
	4182	+ $generated = gmdate( 'Y-m-d H:i:s' ) . ' UTC';
	4183	+ // The literal ' | xspeedcache.com' must survive intact, and what
	4184	+ // precedes it is where an edition suffix lands: Pro appends itself by
	4185	+ // str_replace()-ing on that exact token
	4186	+ // (Pro_Plugin::sign_cache_signature). So the stamp goes AFTER it —
	4187	+ // placed before, it sits between the version and the anchor and
	4188	+ // composes as "generated <date> + Pro v1.1.3".
	4189	+ $signature = sprintf(
	4190	+ '<!-- Page cached by xSpeed Cache v%s | xspeedcache.com | generated %s -->',
	4191	+ $version,
	4192	+ $generated
	4193	+ );
	4194	+
	4195	+ /**
	4196	+ * Filter: xspeed_cache_signature
	4197	+ *
	4198	+ * The HTML comment appended to every cached page. Add-ons append
	4199	+ * their own edition/version here; white-label setups return '' to
	4200	+ * remove the comment entirely. Must remain a valid HTML comment (or
	4201	+ * an empty string) — it ships inside the cached body.
	4202	+ *
	4203	+ * @param string $signature The signature comment.
	4204	+ * @param string $version The plugin version baked into it.
	4205	+ * @param string $generated The write-time timestamp baked into it,
	4206	+ * formatted `Y-m-d H:i:s UTC`.
	4207	+ */
	4208	+ $signature = (string) apply_filters( 'xspeed_cache_signature', $signature, $version, $generated );
	4209	+ if ( '' === trim( $signature ) ) {
	4210	+ return $html;
	4211	+ }
	4212	+ return $html . "\n" . $signature;
	4213	+ }
	4214	+
	4215	+ /**
	4216	+ * Does this response carry a WordPress nonce?
	4217	+ *
	4218	+ * Anonymous nonces depend only on the tick (user 0, empty session
	4219	+ * token), so they are identical for every visitor — which is exactly why
	4220	+ * they cache "successfully" and then fail silently once the tick moves.
	4221	+ *
	4222	+ * Matches any form field whose NAME contains "nonce" — `_wpnonce`,
	4223	+ * `_wpnonce_<action>`, Tutor's `_tutor_nonce`, CF7's `_wpcf7_nonce` and
	4224	+ * WooCommerce's `woocommerce-add-to-cart-nonce` (which does NOT start
	4225	+ * with an underscore, so a `_`-anchored pattern misses it) — plus the
	4226	+ * `_wpnonce=` form used in nonce-bearing URLs. Deliberately keyed on
	4227	+ * `name=` so prose, CSS classes and data attributes don't false-positive.
	4228	+ *
	4229	+ * @param string $html Rendered response body.
	4230	+ */
	4231	+ public static function response_has_nonce( string $html ): bool {
	4232	+ if ( '' === $html ) {
	4233	+ return false;
	4234	+ }
	4235	+
	4236	+ /*
	4237	+ * Three shapes, because a nonce reaches the page in three ways:
	4238	+ *
	4239	+ * 1. A form field name — `_wpnonce`, `woocommerce-login-nonce`, and
	4240	+ * the GROUPED names form builders emit (`data[_wpnonce]`,
	4241	+ * `frm[nonce]`). The character class deliberately allows `[` and
	4242	+ * `]` so grouping does not hide the field: form builders are
	4243	+ * exactly the kind of plugin #236 is about, and a missed page
	4244	+ * keeps the old broken behaviour silently.
	4245	+ * 2. A query argument (`?_wpnonce=`) on a link.
	4246	+ * 3. A nonce handed to the page's own scripts rather than placed in
	4247	+ * a visible form — `wp_localize_script()` output and inline JSON
	4248	+ * both land as a `"nonce":"…"`-shaped pair.
	4249	+ */
	4250	+ return 1 === preg_match(
	4251	+ '/(name=["\'][a-z0-9_\-\[\]]*nonce[a-z0-9_\-\[\]]*["\']'
	4252	+ . '|[?&]_wpnonce='
	4253	+ . '|["\'][a-z0-9_\-]*nonce[a-z0-9_\-]*["\']\s*:\s*["\'][a-f0-9]{8,}["\'])/i',
	4254	+ $html
	4255	+ );
	4256	+ }
	4257	+
	4258	+ /**
	4259	+ * The TTL (seconds) a response may be cached for, capped to the nonce
	4260	+ * lifetime when it carries one.
	4261	+ *
	4262	+ * WordPress nonces are valid for at most `nonce_life` — 24h by default —
	4263	+ * because wp_verify_nonce() accepts the current tick and the previous
	4264	+ * one. Our own lifetime maximum is 720h and the shipped Aggressive
	4265	+ * preset is 168h, so on any site configured above 24h every anonymous
	4266	+ * front-end form carried a DEAD nonce for the majority of the cache's
	4267	+ * life and every submission was rejected — with the other plugin's error
	4268	+ * string ("Nonce not matched"), so the report never reached us (#236).
	4269	+ *
	4270	+ * `nonce_life` is the MAXIMUM a nonce can live, not the minimum, so it
	4271	+ * is the wrong number to cap with. wp_nonce_tick() buckets time into
	4272	+ * `nonce_life / 2` slices; a nonce minted x seconds into its bucket is
	4273	+ * valid for `nonce_life - x`, where x can be as large as a full bucket.
	4274	+ * Capping the entry at `nonce_life` therefore still served a dead nonce
	4275	+ * for up to half of every entry's life — 0-12h of each 24h entry,
	4276	+ * averaging 6h, re-rolled by every purge so it reads as intermittent.
	4277	+ * Capping at the guaranteed-valid remainder closes the window at every
	4278	+ * tick phase, at the cost of caching nonce-bearing pages for 12h rather
	4279	+ * than 24h.
	4280	+ *
	4281	+ * Capping is per-entry, so only nonce-bearing pages pay for it; the rest
	4282	+ * of the site keeps the configured lifetime.
	4283	+ *
	4284	+ * @param string $html Rendered response body.
	4285	+ * @param int $ttl Otherwise-resolved TTL in seconds.
	4286	+ * @return int TTL to actually use.
	4287	+ */
	4288	+ /**
	4289	+ * The nonce lifetime to cap against, in seconds.
	4290	+ *
	4291	+ * `nonce_life` is a TWO-argument filter in core:
	4292	+ *
	4293	+ * $nonce_life = apply_filters( 'nonce_life', DAY_IN_SECONDS, $action );
	4294	+ *
	4295	+ * Applying it with one argument is not merely incomplete — a callback
	4296	+ * that declares both parameters as required (the documented shape, and
	4297	+ * what a site branching per action must write) raises ArgumentCountError
	4298	+ * the moment we call it. That fatal lands in the shutdown cache write,
	4299	+ * so the visitor still sees a perfectly normal page while the sidecar is
	4300	+ * never written: the entry then keeps the FULL configured lifetime
	4301	+ * carrying a dead nonce, which is precisely the bug #236 set out to fix.
	4302	+ * Worse, the entry stays that way until a purge, even after the site
	4303	+ * removes whatever customised the lifetime.
	4304	+ *
	4305	+ * We are inspecting rendered markup, so we cannot know which action
	4306	+ * minted the nonce we found. Two consequences:
	4307	+ *
	4308	+ * 1. We pass `''` as the action. A per-action callback therefore sees
	4309	+ * the same "unknown action" value core itself passes when a nonce is
	4310	+ * created with no action, and can branch on it deliberately.
	4311	+ * 2. A page may carry nonces from SEVERAL actions with different
	4312	+ * lifetimes. The entry can only have one TTL, so the safe choice is
	4313	+ * the SHORTEST lifetime any action on the site resolves to — capping
	4314	+ * to a longer one would serve a dead nonce for the shorter action.
	4315	+ * Sites can narrow this with `xspeed_cache_nonce_life_actions`.
	4316	+ *
	4317	+ * @param string $html Response body being cached.
	4318	+ * @return int Nonce lifetime in seconds (0 = do not cap).
	4319	+ */
	4320	+ private static function nonce_life_seconds( string $html ): int {
	4321	+ /**
	4322	+ * Filter the nonce actions whose lifetimes are consulted when
	4323	+ * capping a cache entry.
	4324	+ *
	4325	+ * The default `''` is the "action unknown" case — we are reading
	4326	+ * rendered HTML, not minting a nonce. A site whose `nonce_life`
	4327	+ * callback shortens specific actions can list them here so the cap
	4328	+ * accounts for the shortest one that could appear on the page.
	4329	+ *
	4330	+ * @since 1.1.8
	4331	+ * @param string[] $actions Nonce actions to resolve.
	4332	+ * @param string $html The response body being cached.
	4333	+ */
	4334	+ $actions = (array) apply_filters( 'xspeed_cache_nonce_life_actions', array( '' ), $html );
	4335	+ if ( empty( $actions ) ) {
	4336	+ $actions = array( '' );
	4337	+ }
	4338	+
	4339	+ $shortest = 0;
	4340	+ foreach ( $actions as $action ) {
	4341	+ // Both arguments, exactly as core passes them.
	4342	+ $life = (int) apply_filters( 'nonce_life', DAY_IN_SECONDS, (string) $action );
	4343	+ if ( $life < 1 ) {
	4344	+ continue;
	4345	+ }
	4346	+ if ( 0 === $shortest || $life < $shortest ) {
	4347	+ $shortest = $life;
	4348	+ }
	4349	+ }
	4350	+
	4351	+ return $shortest;
	4352	+ }
	4353	+
	4354	+ public static function nonce_capped_ttl( string $html, int $ttl ): int {
	4355	+ if ( ! self::response_has_nonce( $html ) ) {
	4356	+ return $ttl;
	4357	+ }
	4358	+
	4359	+ $nonce_life = self::nonce_life_seconds( $html );
	4360	+ if ( $nonce_life < 1 ) {
	4361	+ return $ttl;
	4362	+ }
	4363	+
	4364	+ // Half of nonce_life is the GUARANTEED-valid remainder — see above.
	4365	+ $guaranteed = max( 1, intdiv( $nonce_life, 2 ) );
	4366	+ $capped = ( $ttl > 0 ) ? min( $ttl, $guaranteed ) : $guaranteed;
	4367	+
	4368	+ /**
	4369	+ * Filter the nonce-capped TTL for a cache entry.
	4370	+ *
	4371	+ * Escape hatch for a site whose nonce-shaped markup is decorative —
	4372	+ * return the uncapped $ttl to keep the configured lifetime. Most
	4373	+ * sites should leave this alone: serving a dead nonce breaks every
	4374	+ * anonymous form on the page.
	4375	+ *
	4376	+ * @param int $capped TTL after the nonce cap (seconds).
	4377	+ * @param int $ttl TTL before the cap (seconds).
	4378	+ * @param int $nonce_life Current nonce lifetime (seconds).
	4379	+ * @param string $html The response body being cached.
	4380	+ */
	4381	+ return (int) apply_filters( 'xspeed_cache_nonce_ttl_cap', $capped, $ttl, $nonce_life, $html );
	4382	+ }
	4383	+
	4384	+ private static function write_meta( string $key, string $html = '' ): void {
801	4385	$content_type = '';
802	4386	foreach ( headers_list() as $header ) {
803	4387	if ( 0 === stripos( $header, 'content-type:' ) ) {
804	4388	$content_type = trim( substr( $header, strlen( 'content-type:' ) ) );
		@@ -819,15 +4403,52 @@
819	4403	// call is_expired() / the xspeed_cache_max_age filter (they run before
820	4404	// WP), so persist the resolved max-age here whenever it differs from
821	4405	// the plain page TTL — e.g. the Pro feed cache's 12h vs the 24h page
822	4406	// default. The fast paths read this to expire correctly. (FBS-82407)
823		- $opts = Settings_Manager::get( 'cache' );
824		- $default_ttl = (int) $opts['cache_expiry'] * HOUR_IN_SECONDS;
825		- $ttl = (int) apply_filters( 'xspeed_cache_max_age', $default_ttl );
	4407	+ // This MUST resolve the TTL the same way is_expired() does, including
	4408	+ // the per-post override — the sidecar is the only channel that can
	4409	+ // carry a per-entry TTL into the pre-boot fast paths. Omitting the
	4410	+ // override here left an editor's "expire this post after 1h" visible
	4411	+ // to the engine but invisible to the drop-in, which kept serving the
	4412	+ // entry until the global lifetime elapsed (#240 AC#3). Handing the
	4413	+ // filter the same base as is_expired() also keeps a filter that
	4414	+ // SCALES its input (e.g. $max_age * 2) consistent between the two.
	4415	+ $opts = Settings_Manager::get( 'cache' );
	4416	+ $default_ttl = (int) $opts['cache_expiry'] * HOUR_IN_SECONDS;
	4417	+ $max_age = $default_ttl;
	4418	+ $post_override = Cache_Rules::expiry_override_seconds_for_post( Cache_Rules::current_post_id() );
	4419	+ if ( null !== $post_override ) {
	4420	+ $max_age = $post_override;
	4421	+ }
	4422	+ /** This filter is documented in includes/class-cache.php */
	4423	+ $ttl = (int) apply_filters( 'xspeed_cache_max_age', $max_age );
	4424	+
	4425	+ // A response carrying a nonce may not outlive that nonce, however
	4426	+ // long the site's configured lifetime is (#236). This runs AFTER the
	4427	+ // max-age filter so it caps whatever the filter resolved rather than
	4428	+ // being overridden by it — a Pro module lengthening the TTL must not
	4429	+ // be able to reintroduce a dead nonce.
	4430	+ $ttl = self::nonce_capped_ttl( $html, $ttl );
	4431	+
826	4432	if ( $ttl > 0 && $ttl !== $default_ttl ) {
827	4433	$meta['ttl'] = $ttl;
828	4434	}
829	4435
	4436	+ // This entry's edge headers, when they differ from the site-wide set
	4437	+ // baked into the drop-in. The sidecar is the only channel that can
	4438	+ // carry a per-page answer into the pre-boot fast path, and the drop-in
	4439	+ // REPLACES the baked set with it rather than merging: the two describe
	4440	+ // the same response, so merging would leave the baked lifetime in
	4441	+ // place beside the hold meant to overrule it.
	4442	+ //
	4443	+ // The lifetime resolved above goes with it, under the same condition
	4444	+ // as the `ttl` key: a page that does not follow the site's lifetime
	4445	+ // may not be kept at the edge past its own either.
	4446	+ $edge = self::per_entry_edge_headers( isset( $meta['ttl'] ) ? $ttl : null );
	4447	+ if ( array() !== $edge ) {
	4448	+ $meta['edge_headers'] = $edge;
	4449	+ }
	4450	+
830	4451	// Nothing to replay → no sidecar.
831	4452	if ( empty( $meta ) ) {
832	4453	return;
833	4454	}
		@@ -845,49 +4466,2189 @@
845	4466	* Activity log to give users context (e.g.
846	4467	* 'post saved', 'settings change', 'manual',
847	4468	* 'theme switch').
848	4469	*/
849		- public static function purge_all( string $cause = 'manual' ) {
	4470	+ /**
	4471	+ * Purge the cache entries for ONE URL — every variant of it: the
	4472	+ * flat-hash entry (+ .meta / .html.br siblings), both device buckets
	4473	+ * (mobile_separate keys them separately), both trailing-slash forms,
	4474	+ * and the static-tree index.html (+ .br) the server rewrite serves.
	4475	+ * The rest of the cache is untouched — this is the surgical
	4476	+ * alternative to purge_all for "I just edited this one page".
	4477	+ *
	4478	+ * @param string $url Absolute URL, or site-relative path ("/about/").
	4479	+ * @param string $cause Who asked, for the purge log. See purge_all().
	4480	+ * @return int Number of cache files removed.
	4481	+ */
	4482	+ /**
	4483	+ * Post types that are not "viewable" but ARE the presentation layer.
	4484	+ *
	4485	+ * `is_post_type_viewable()` answers "does this type have a front end of
	4486	+ * its own?" — which is the right question for `shop_order`, but the
	4487	+ * wrong one for the types core uses to render every OTHER page. A
	4488	+ * template part, a global-styles record, a navigation or a synced
	4489	+ * pattern has no permalink, yet editing one changes how the whole site
	4490	+ * looks. Gating purges on viewability alone meant a Site Editor save
	4491	+ * invalidated nothing and visitors kept the old design for the full
	4492	+ * TTL — up to 30 days at the maximum lifetime. (#270 regression)
	4493	+ *
	4494	+ * @return string[]
	4495	+ */
	4496	+ /**
	4497	+ * Could this post change alter anything an anonymous visitor had cached?
	4498	+ *
	4499	+ * Deleting one post fired a full purge for the post AND for every stored
	4500	+ * revision, because wp_delete_post() removes each revision through
	4501	+ * wp_delete_post() again and every one of those fires before_delete_post
	4502	+ * with post_type 'revision'. A post with six revisions cost seven whole-
	4503	+ * site sweeps, each one also announcing to LiteSpeed, purging the object
	4504	+ * cache network-wide on Redis, rewriting the stats option and running
	4505	+ * every xspeed_after_purge_all listener -- including Pro's Cloudflare
	4506	+ * purge, so seven API calls. Trashing cost two, via save_post and then
	4507	+ * trashed_post. (QA #348)
	4508	+ *
	4509	+ * The check lives here, ahead of purge_all(), so one early return covers
	4510	+ * the local sweep, the server-cache announcement and both action hooks.
	4511	+ * It deliberately does NOT live inside purge_all(): a manual, CLI or
	4512	+ * explicit caller asked for a purge and must get one.
	4513	+ *
	4514	+ * @param int $post_id Post being saved or removed.
	4515	+ * @param mixed $post Post object when the hook passed one.
	4516	+ * @param string $event 'save' or 'remove'.
	4517	+ */
	4518	+ private static function post_change_is_cacheable_content( $post_id, $post, string $event ): bool {
	4519	+ $post_id = (int) $post_id;
	4520	+
	4521	+ // Only `save_post` and `before_delete_post` hand over a post object.
	4522	+ // `trashed_post` passes ( $post_id, $previous_status ) -- a STRING --
	4523	+ // so reaching for ->post_status on the second argument finds nothing
	4524	+ // and the status rule below would never fire. Read the row instead.
	4525	+ if ( ! is_object( $post ) && function_exists( 'get_post' ) ) {
	4526	+ $post = get_post( $post_id );
	4527	+ }
	4528	+
	4529	+ $type = is_object( $post ) && isset( $post->post_type )
	4530	+ ? (string) $post->post_type
	4531	+ : (string) ( function_exists( 'get_post_type' ) ? get_post_type( $post_id ) : '' );
	4532	+ if ( '' === $type ) {
	4533	+ return false;
	4534	+ }
	4535	+
	4536	+ // A revision is a copy of content nobody can browse to.
	4537	+ if ( 'revision' === $type ) {
	4538	+ return false;
	4539	+ }
	4540	+ if ( function_exists( 'wp_is_post_revision' ) && wp_is_post_revision( $post_id ) ) {
	4541	+ return false;
	4542	+ }
	4543	+ if ( function_exists( 'wp_is_post_autosave' ) && wp_is_post_autosave( $post_id ) ) {
	4544	+ return false;
	4545	+ }
	4546	+
	4547	+ $status = is_object( $post ) && isset( $post->post_status ) ? (string) $post->post_status : '';
	4548	+
	4549	+ // Clicking "Add New" inserts an auto-draft and fires save_post. There
	4550	+ // is nothing cached of a post that has never existed publicly.
	4551	+ if ( 'auto-draft' === $status ) {
	4552	+ return false;
	4553	+ }
	4554	+
	4555	+ // Unknown/!viewable → nothing anonymous can see changed, UNLESS the
	4556	+ // type is itself part of how pages render (#270 regression).
	4557	+ if ( function_exists( 'is_post_type_viewable' )
	4558	+ && ! is_post_type_viewable( $type )
	4559	+ && ! in_array( $type, self::presentation_post_types(), true )
	4560	+ ) {
	4561	+ return false;
	4562	+ }
	4563	+
	4564	+ // Deleting something that was already invisible changes no cached
	4565	+ // page: the transition that hid it purged at the time. This is what
	4566	+ // makes emptying a trash of a hundred posts cost nothing rather than
	4567	+ // a hundred full sweeps.
	4568	+ //
	4569	+ // It also collapses trashing to a single purge: wp_trash_post() fires
	4570	+ // save_post first, where the post is genuinely disappearing from
	4571	+ // listings and SHOULD purge, then trashed_post, by which point the
	4572	+ // row reads 'trash' and is skipped. A status we cannot read, on a row
	4573	+ // that still reports a type, means assume viewable -- erring toward
	4574	+ // an extra purge, never toward serving a stale page. A row that is
	4575	+ // gone entirely reports no type either and was refused above.
	4576	+ // 'inherit' is an INTERNAL status in core, so is_post_status_viewable()
	4577	+ // says no -- but an attachment carrying it is genuinely public. Judge
	4578	+ // those on the post type alone, which is already checked above.
	4579	+ if ( 'remove' === $event && '' !== $status && 'inherit' !== $status
	4580	+ && function_exists( 'is_post_status_viewable' )
	4581	+ && ! is_post_status_viewable( $status )
	4582	+ ) {
	4583	+ return false;
	4584	+ }
	4585	+
	4586	+ return true;
	4587	+ }
	4588	+
	4589	+ public static function presentation_post_types(): array {
	4590	+ $types = array(
	4591	+ 'wp_template', // Site Editor templates.
	4592	+ 'wp_template_part', // Header / footer / reusable parts.
	4593	+ 'wp_global_styles', // Colours, typography, spacing.
	4594	+ 'wp_navigation', // Navigation block menus.
	4595	+ 'nav_menu_item', // Classic menus.
	4596	+ 'wp_block', // Synced patterns / reusable blocks.
	4597	+ );
	4598	+
	4599	+ /**
	4600	+ * Filter the non-viewable post types that still invalidate the cache.
	4601	+ *
	4602	+ * Add a type here when it has no front end of its own but changes
	4603	+ * how other pages render (a theme's own layout CPT, for example).
	4604	+ *
	4605	+ * @param string[] $types Post type slugs.
	4606	+ */
	4607	+ return (array) apply_filters( 'xspeed_presentation_post_types', $types );
	4608	+ }
	4609	+
	4610	+ /**
	4611	+ * Describe a broad hook invalidation for response-cache adapters.
	4612	+ *
	4613	+ * Term, menu, theme and plugin changes can alter navigation, archives or
	4614	+ * markup across the site, so they require a site response-cache purge.
	4615	+ * Content saves also require this scope while their local operation is a
	4616	+ * complete bucket sweep.
	4617	+ *
	4618	+ * A new term is `content`, not `presentation`. It has no posts yet, so no
	4619	+ * page renders it until a post is saved with it, and that save is its own
	4620	+ * content purge. Classed as presentation, it cleared the host's whole
	4621	+ * nginx cache every time a post was published with a tag that did not
	4622	+ * exist yet, which is most publishing. Renaming or deleting a term stays
	4623	+ * presentation: the new name shows on every post in the term, and Nginx
	4624	+ * Helper purges only the homepage for either. (QA #448)
	4625	+ *
	4626	+ * @return array{scope:string,intent:string,urls:array<int,string>}
	4627	+ */
	4628	+ private static function invalidation_for_hook( string $hook ): array {
	4629	+ $presentation = array(
	4630	+ 'switch_theme',
	4631	+ 'activated_plugin',
	4632	+ 'deactivated_plugin',
	4633	+ 'edited_term',
	4634	+ 'delete_term',
	4635	+ 'wp_update_nav_menu',
	4636	+ );
	4637	+
	4638	+ return array(
	4639	+ 'scope' => 'site',
	4640	+ 'intent' => in_array( $hook, $presentation, true ) ? 'presentation' : 'content',
	4641	+ 'urls' => array(),
	4642	+ );
	4643	+ }
	4644	+
	4645	+
	4646	+ /**
	4647	+ * save_post → purge only when the saved thing can appear on a cached page.
	4648	+ *
	4649	+ * Revisions and autosaves are never rendered. Non-viewable post types —
	4650	+ * WooCommerce's `shop_order` / `shop_order_placehold` / `shop_order_refund`
	4651	+ * / `shop_coupon`, Flamingo's `flamingo_inbound` (#229), Tutor's
	4652	+ * `tutor_enrolled` (#231) — are invisible to anonymous visitors, so
	4653	+ * writing one changes nothing that is cached. (#243)
	4654	+ *
	4655	+ * The exception is the presentation types above, which are non-viewable
	4656	+ * yet render every page — they are allow-listed BEFORE the viewability
	4657	+ * test. (#270 regression)
	4658	+ *
	4659	+ * @param int $post_id Saved post ID.
	4660	+ * @param \WP_Post $post Saved post object.
	4661	+ */
	4662	+ public static function on_save_post( $post_id, $post = null ): void {
	4663	+ if ( ! self::post_change_is_cacheable_content( $post_id, $post, 'save' ) ) {
	4664	+ return;
	4665	+ }
	4666	+
	4667	+ $post_type = is_object( $post ) && isset( $post->post_type )
	4668	+ ? (string) $post->post_type
	4669	+ : (string) get_post_type( $post_id );
	4670	+
	4671	+ // Name the trigger rather than logging a bare numeric id — the old
	4672	+ // wiring passed the post ID into $cause, so the log read
	4673	+ // "Cache purged (46)" with no indication of what caused it. (#243)
	4674	+ $presentation = in_array( $post_type, self::presentation_post_types(), true );
	4675	+
	4676	+ // Clearing only the affected pages needs the post's terms, and the
	4677	+ // REST API sets those after `save_post`. Note the post and purge on
	4678	+ // `wp_after_insert_post`; flush_pending_saves() covers a save that
	4679	+ // never gets there.
	4680	+ if ( ! $presentation && self::narrow_purge_applies( $post_type ) ) {
	4681	+ self::$pending_saves[ (int) $post_id ] = true;
	4682	+ return;
	4683	+ }
	4684	+
	4685	+ self::purge_all(
	4686	+ 'post:' . $post_type,
	4687	+ null,
	4688	+ array(
	4689	+ // purge_all() sweeps every local response in this site's bucket.
	4690	+ // Without dependency tracking, the server cache must match that
	4691	+ // same boundary or unrelated pages can remain stale there.
	4692	+ 'scope' => 'site',
	4693	+ 'intent' => $presentation ? 'presentation' : 'content',
	4694	+ 'urls' => array(),
	4695	+ )
	4696	+ );
	4697	+ }
	4698	+
	4699	+ /**
	4700	+ * Reasons a change that would have cleared only its own pages cleared
	4701	+ * the whole site, published as `fallback` in the purge context.
	4702	+ *
	4703	+ * - THEME_LIST: the change alters a post or comment list the theme draws
	4704	+ * on pages the rules cannot name.
	4705	+ * - LIMIT: the affected pages are more than Affected_Pages::LIMIT.
	4706	+ * - PENDING: the save never reached `wp_after_insert_post`, so there was
	4707	+ * no before-copy to work the old address out from.
	4708	+ * - FILTER: `xspeed_purge_affected_pages` returned false.
	4709	+ * - LISTING: the record of pages that run a post list of their own
	4710	+ * (Listing_Pages) cannot answer: a page of the type went unrecorded at
	4711	+ * its cap, more than Affected_Pages::LIMIT pages of the type would
	4712	+ * have to be named, or the index does not read back. Or the pages it
	4713	+ * named took the list past Affected_Pages::LIMIT.
	4714	+ *
	4715	+ * Every other purge publishes ''. A post type that always purges the
	4716	+ * whole site (a WooCommerce product) is a choice, not a fallback, and
	4717	+ * publishes '' too.
	4718	+ */
	4719	+ public const FALLBACK_THEME_LIST = 'theme_list';
	4720	+ public const FALLBACK_LIMIT = 'limit';
	4721	+ public const FALLBACK_PENDING = 'pending';
	4722	+ public const FALLBACK_FILTER = 'filter';
	4723	+ public const FALLBACK_LISTING = 'listing';
	4724	+
	4725	+ /**
	4726	+ * Posts noted by on_save_post() for a narrow purge, keyed by ID.
	4727	+ *
	4728	+ * @var array<int,bool>
	4729	+ */
	4730	+ private static $pending_saves = array();
	4731	+
	4732	+ /**
	4733	+ * Posts whose save purged their pages in this request, keyed by ID. That
	4734	+ * purge named page 1 of the posts page, so a sticky change made after
	4735	+ * it (the classic editor and Quick Edit stick after saving) has nothing
	4736	+ * left to clear there.
	4737	+ *
	4738	+ * @var array<int,bool>
	4739	+ */
	4740	+ private static $saves_purged = array();
	4741	+
	4742	+ /**
	4743	+ * Purge the pages a save affected, once WordPress has finished saving.
	4744	+ *
	4745	+ * @param int $post_id Post ID.
	4746	+ * @param \WP_Post $post Post as saved.
	4747	+ * @param bool $update Whether an existing post was updated.
	4748	+ * @param \WP_Post|null $post_before Post before the save, null when new.
	4749	+ */
	4750	+ public static function on_after_insert_post( $post_id, $post = null, $update = false, $post_before = null ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- hook signature.
	4751	+ $post_id = (int) $post_id;
	4752	+ if ( ! isset( self::$pending_saves[ $post_id ] ) ) {
	4753	+ return;
	4754	+ }
	4755	+ unset( self::$pending_saves[ $post_id ] );
	4756	+ if ( ! $post instanceof \WP_Post ) {
	4757	+ $post = get_post( $post_id );
	4758	+ }
	4759	+ if ( ! $post instanceof \WP_Post ) {
	4760	+ return;
	4761	+ }
	4762	+ $post_before = $post_before instanceof \WP_Post ? $post_before : null;
	4763	+ if ( self::repeats_block_editor_save( $post, $post_before ) ) {
	4764	+ Affected_Pages::forget( $post_id );
	4765	+ return;
	4766	+ }
	4767	+ self::$saves_purged[ $post_id ] = true;
	4768	+ self::purge_post_change( $post, $post_before, 'post:' . $post->post_type );
	4769	+ }
	4770	+
	4771	+ /** Meta WordPress rewrites on every save, which says nothing about the page. */
	4772	+ private const SAVE_NOISE_META = array( '_edit_lock', '_edit_last', '_encloseme', '_pingme' );
	4773	+
	4774	+ /**
	4775	+ * Whether this save repeats the block editor save that just purged.
	4776	+ *
	4777	+ * The block editor saves a post through REST, then, when the screen has
	4778	+ * meta boxes (xSpeed's own Cache Rules box is one), posts them to
	4779	+ * post.php?meta-box-loader=1, which saves the post a second time. Both
	4780	+ * requests purged, so every save sent the same pages to every cache in
	4781	+ * front twice. The REST save notes what it purged for; the meta box
	4782	+ * request skips its purge when nothing a visitor sees has changed since:
	4783	+ * the post's fields, its terms and its meta. A meta box that saved meta
	4784	+ * the page prints (an SEO title, a custom field) still purges.
	4785	+ *
	4786	+ * @param \WP_Post $post Post as saved.
	4787	+ * @param \WP_Post|null $before Post before the save.
	4788	+ */
	4789	+ private static function repeats_block_editor_save( \WP_Post $post, ?\WP_Post $before ): bool {
	4790	+ // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- only names the request; WordPress verified the save's own nonce.
	4791	+ $meta_boxes = isset( $_GET['meta-box-loader'] );
	4792	+ $rest = defined( 'REST_REQUEST' ) && REST_REQUEST;
	4793	+ if ( ! $meta_boxes && ! $rest ) {
	4794	+ return false;
	4795	+ }
	4796	+ if ( ! Affected_Pages::is_public( $post ) && ! ( $before instanceof \WP_Post && Affected_Pages::is_public( $before ) ) ) {
	4797	+ return false;
	4798	+ }
	4799	+ $key = 'xspeed_saved_' . (int) $post->ID;
	4800	+ $fingerprint = self::save_fingerprint( $post );
	4801	+ if ( $meta_boxes ) {
	4802	+ if ( get_transient( $key ) === $fingerprint ) {
	4803	+ delete_transient( $key );
	4804	+ return true;
	4805	+ }
	4806	+ return false;
	4807	+ }
	4808	+ set_transient( $key, $fingerprint, 2 * MINUTE_IN_SECONDS );
	4809	+ return false;
	4810	+ }
	4811	+
	4812	+ /**
	4813	+ * A hash of what a save can change that a visitor sees: the post's own
	4814	+ * fields, its terms and its meta.
	4815	+ *
	4816	+ * @param \WP_Post $post Post as saved.
	4817	+ */
	4818	+ private static function save_fingerprint( \WP_Post $post ): string {
	4819	+ $fields = array();
	4820	+ foreach ( array( 'post_type', 'post_status', 'post_date', 'post_title', 'post_name', 'post_content', 'post_excerpt', 'post_parent', 'menu_order', 'post_author', 'post_password', 'comment_status' ) as $field ) {
	4821	+ $fields[ $field ] = (string) ( $post->$field ?? '' );
	4822	+ }
	4823	+ $terms = array();
	4824	+ $taxonomies = get_object_taxonomies( (string) $post->post_type );
	4825	+ if ( is_array( $taxonomies ) && array() !== $taxonomies ) {
	4826	+ $ids = wp_get_object_terms( (int) $post->ID, $taxonomies, array( 'fields' => 'tt_ids' ) );
	4827	+ $terms = is_array( $ids ) ? array_map( 'intval', $ids ) : array();
	4828	+ sort( $terms );
	4829	+ }
	4830	+ $meta = get_post_meta( (int) $post->ID );
	4831	+ $meta = is_array( $meta ) ? array_diff_key( $meta, array_flip( self::SAVE_NOISE_META ) ) : array();
	4832	+ ksort( $meta );
	4833	+ return md5( (string) wp_json_encode( array( $fields, $terms, $meta ) ) );
	4834	+ }
	4835	+
	4836	+ /**
	4837	+ * A save that never reached `wp_after_insert_post` still purges.
	4838	+ *
	4839	+ * `wp_insert_post()` called with `$fire_after_hooks = false` leaves that
	4840	+ * hook to its caller, and a caller can fail to fire it. Without this, the
	4841	+ * save would purge nothing at all. Site-wide, because there is no
	4842	+ * before-copy to work out the old address from.
	4843	+ */
	4844	+ public static function flush_pending_saves(): void {
	4845	+ if ( array() === self::$pending_saves ) {
	4846	+ return;
	4847	+ }
	4848	+ $ids = array_keys( self::$pending_saves );
	4849	+ self::$pending_saves = array();
	4850	+ self::purge_all(
	4851	+ 'post:pending',
	4852	+ null,
	4853	+ array(
	4854	+ 'scope' => 'site',
	4855	+ 'intent' => 'content',
	4856	+ 'urls' => array(),
	4857	+ 'fallback' => self::FALLBACK_PENDING,
	4858	+ )
	4859	+ );
	4860	+ foreach ( $ids as $id ) {
	4861	+ Affected_Pages::forget( (int) $id );
	4862	+ }
	4863	+ }
	4864	+
	4865	+ /**
	4866	+ * Before an update is written: note the post's neighbours, which a new
	4867	+ * date or category takes it away from. Only for a post visitors can see
	4868	+ * now, and only when the save will purge narrowly; that costs four
	4869	+ * queries per update.
	4870	+ *
	4871	+ * @param int $post_id Post ID.
	4872	+ * @param array $data Unused: the new values.
	4873	+ */
	4874	+ public static function on_pre_post_update( $post_id, $data = array() ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundAfterLastUsed -- hook signature.
	4875	+ $post = get_post( (int) $post_id );
	4876	+ if ( ! $post instanceof \WP_Post || ! Affected_Pages::is_public( $post ) ) {
	4877	+ return;
	4878	+ }
	4879	+ if ( in_array( (string) $post->post_type, self::presentation_post_types(), true ) || ! self::narrow_purge_applies( (string) $post->post_type ) ) {
	4880	+ return;
	4881	+ }
	4882	+ Affected_Pages::remember_old_neighbours( $post );
	4883	+ }
	4884	+
	4885	+ /**
	4886	+ * A post was stuck or unstuck.
	4887	+ *
	4888	+ * A theme list that puts sticky posts first (Twenty Twenty-Five's "More
	4889	+ * posts" under every post) changes on every page that draws it, so the
	4890	+ * whole site goes. The block editor changes stickiness inside the save,
	4891	+ * and the save's own purge sees it then. The classic editor and Quick
	4892	+ * Edit change it after the save has purged, which is why this hook
	4893	+ * purges the posts no save is waiting on.
	4894	+ *
	4895	+ * @param mixed $old_value Sticky post IDs before.
	4896	+ * @param mixed $value Sticky post IDs after.
	4897	+ */
	4898	+ public static function on_sticky_posts_change( $old_value, $value ): void {
	4899	+ $blog_page = false;
	4900	+ foreach ( Affected_Pages::remember_sticky_change( $old_value, $value ) as $post_id ) {
	4901	+ if ( isset( self::$pending_saves[ $post_id ] ) ) {
	4902	+ continue;
	4903	+ }
	4904	+ $post = get_post( $post_id );
	4905	+ if ( ! $post instanceof \WP_Post || ! Affected_Pages::is_public( $post ) || ! self::narrow_purge_applies( (string) $post->post_type ) ) {
	4906	+ continue;
	4907	+ }
	4908	+ if ( Affected_Pages::lists_show_sticky( (string) $post->post_type ) ) {
	4909	+ self::purge_all(
	4910	+ 'sticky:' . $post->post_type,
	4911	+ null,
	4912	+ array(
	4913	+ 'scope' => 'site',
	4914	+ 'intent' => 'content',
	4915	+ 'urls' => array(),
	4916	+ 'fallback' => self::FALLBACK_THEME_LIST,
	4917	+ )
	4918	+ );
	4919	+ return;
	4920	+ }
	4921	+ // WordPress's own blog list puts sticky posts first on its first
	4922	+ // page, whatever the theme draws, so a post stuck or unstuck by
	4923	+ // code, WP-CLI or a plugin moves on that page. A save in this
	4924	+ // request already cleared it.
	4925	+ if ( 'post' === $post->post_type && ! isset( self::$saves_purged[ $post_id ] ) ) {
	4926	+ $blog_page = true;
	4927	+ }
	4928	+ }
	4929	+ if ( $blog_page ) {
	4930	+ $url = Affected_Pages::posts_page_url();
	4931	+ if ( '' !== $url ) {
	4932	+ self::purge_urls( array( $url ), 'sticky:post' );
	4933	+ }
	4934	+ }
	4935	+ }
	4936	+
	4937	+ /**
	4938	+ * The first post stuck on a site: WordPress creates `sticky_posts`
	4939	+ * instead of updating it, so update_option_sticky_posts never fires.
	4940	+ *
	4941	+ * @param string $option Option name.
	4942	+ * @param mixed $value Sticky post IDs.
	4943	+ */
	4944	+ public static function on_sticky_posts_added( $option, $value ): void { // phpcs:ignore Generic.CodeAnalysis.UnusedFunctionParameter.FoundBeforeLastUsed -- hook signature.
	4945	+ self::on_sticky_posts_change( array(), $value );
	4946	+ }
	4947	+
	4948	+ /**
	4949	+ * Whether a content change to this post type may clear only the pages
	4950	+ * it affects, before looking at the post itself.
	4951	+ *
	4952	+ * Off when the setting is off, during an import (one full purge runs at
	4953	+ * the end), and for post types whose lists the rules do not know:
	4954	+ * WooCommerce products, whose shop and category pages purge_product()
	4955	+ * already handles.
	4956	+ *
	4957	+ * @param string $post_type Post type.
	4958	+ */
	4959	+ private static function narrow_purge_applies( string $post_type ): bool {
	4960	+ if ( defined( 'WP_IMPORTING' ) && WP_IMPORTING ) {
	4961	+ return false;
	4962	+ }
	4963	+ $opts = Settings_Manager::get( 'cache' );
	4964	+ if ( empty( $opts['purge_affected_only'] ) ) {
	4965	+ return false;
	4966	+ }
	4967	+ /**
	4968	+ * Filter the post types whose saves always purge the whole site.
	4969	+ *
	4970	+ * @param string[] $types Post type slugs.
	4971	+ */
	4972	+ $site_wide = (array) apply_filters( 'xspeed_site_wide_purge_post_types', array( 'product', 'product_variation' ) );
	4973	+ return ! in_array( $post_type, $site_wide, true );
	4974	+ }
	4975	+
	4976	+ /**
	4977	+ * Purge what a change to one post affects, or the whole site when the
	4978	+ * affected pages cannot be listed safely.
	4979	+ *
	4980	+ * The pages are the ones the rules name (Affected_Pages::for_post())
	4981	+ * and the recorded pages whose own post lists the change may alter
	4982	+ * (Listing_Pages::pages_for()).
	4983	+ *
	4984	+ * Site-wide when this change alters a post list the theme draws on
	4985	+ * pages the rules cannot name (Affected_Pages::lists_changed_by()), when
	4986	+ * the record of listing pages cannot answer, when the list is
	4987	+ * longer than Affected_Pages::LIMIT, or when the filter says so. Nothing
	4988	+ * when the post was not public before or after: no page anyone can see
	4989	+ * changed.
	4990	+ *
	4991	+ * @param \WP_Post $post Post as it is now.
	4992	+ * @param \WP_Post|null $before Post before the change.
	4993	+ * @param string $cause Purge log cause.
	4994	+ */
	4995	+ private static function purge_post_change( \WP_Post $post, ?\WP_Post $before, string $cause ): void {
	4996	+ // Checked before any list is consulted. A draft save moves the
	4997	+ // draft's date and can match a list of any kind, which would send a
	4998	+ // change nobody can see to a site-wide purge.
	4999	+ if ( ! Affected_Pages::is_public( $post ) && ! ( $before instanceof \WP_Post && Affected_Pages::is_public( $before ) ) ) {
	5000	+ Affected_Pages::forget( (int) $post->ID );
	5001	+ return;
	5002	+ }
	5003	+ $fallback = '';
	5004	+ $urls = null;
	5005	+ if ( Affected_Pages::lists_changed_by( $post, $before ) ) {
	5006	+ $fallback = self::FALLBACK_THEME_LIST;
	5007	+ } else {
	5008	+ $urls = Affected_Pages::for_post( $post, $before );
	5009	+ // Read before forget(): a plain edit is judged on the terms the
	5010	+ // save replaced.
	5011	+ $listing = Listing_Pages::enabled() ? Listing_Pages::pages_for( $post, $before ) : array();
	5012	+ if ( null === $listing ) {
	5013	+ $fallback = self::FALLBACK_LISTING;
	5014	+ $urls = null;
	5015	+ } else {
	5016	+ // Pages the rules did not name. Nginx Helper's own purge does
	5017	+ // not reach them either, so a fallback they cause has to say so.
	5018	+ $extra = array_diff( $listing, $urls );
	5019	+ $urls = array_values( array_unique( array_merge( $urls, $listing ) ) );
	5020	+ if ( count( $urls ) > Affected_Pages::LIMIT ) {
	5021	+ $fallback = array() === $extra ? self::FALLBACK_LIMIT : self::FALLBACK_LISTING;
	5022	+ $urls = null;
	5023	+ }
	5024	+ }
	5025	+ }
	5026	+ Affected_Pages::forget( (int) $post->ID );
	5027	+
	5028	+ if ( is_array( $urls ) ) {
	5029	+ /**
	5030	+ * Filter the pages a post change clears.
	5031	+ *
	5032	+ * Return false to purge the whole site instead.
	5033	+ *
	5034	+ * @param string[]|false $urls Absolute URLs.
	5035	+ * @param \WP_Post $post The post that changed.
	5036	+ */
	5037	+ $urls = apply_filters( 'xspeed_purge_affected_pages', $urls, $post );
	5038	+ if ( ! is_array( $urls ) ) {
	5039	+ $fallback = self::FALLBACK_FILTER;
	5040	+ }
	5041	+ }
	5042	+
	5043	+ if ( ! is_array( $urls ) ) {
	5044	+ self::purge_all(
	5045	+ $cause,
	5046	+ null,
	5047	+ array(
	5048	+ 'scope' => 'site',
	5049	+ 'intent' => 'content',
	5050	+ 'urls' => array(),
	5051	+ 'fallback' => $fallback,
	5052	+ )
	5053	+ );
	5054	+ return;
	5055	+ }
	5056	+ if ( array() !== $urls ) {
	5057	+ self::purge_urls( $urls, $cause );
	5058	+ }
	5059	+ }
	5060	+
	5061	+ /**
	5062	+ * Delete/trash invalidation while the post type is still available.
	5063	+ * The local and server response-cache sweeps share the same site boundary.
	5064	+ *
	5065	+ * @param int $post_id Removed post ID.
	5066	+ * @param object|null $post Post object supplied by core when available.
	5067	+ */
	5068	+ public static function on_post_removed( $post_id, $post = null ): void {
	5069	+ if ( ! self::post_change_is_cacheable_content( $post_id, $post, 'remove' ) ) {
	5070	+ return;
	5071	+ }
	5072	+
	5073	+ $post_type = is_object( $post ) && isset( $post->post_type )
	5074	+ ? (string) $post->post_type
	5075	+ : (string) get_post_type( $post_id );
	5076	+
	5077	+ if ( ! in_array( $post_type, self::presentation_post_types(), true ) && self::narrow_purge_applies( $post_type ) ) {
	5078	+ $object = $post instanceof \WP_Post ? $post : get_post( (int) $post_id );
	5079	+ if ( $object instanceof \WP_Post ) {
	5080	+ if ( 'attachment' === $post_type ) {
	5081	+ // Its own page and the post it is attached to. Pages that
	5082	+ // show the file keep an <img> to a file that is gone either
	5083	+ // way: a fresh render prints the same tag.
	5084	+ $urls = array();
	5085	+ $link = get_permalink( $object );
	5086	+ if ( is_string( $link ) && '' !== $link ) {
	5087	+ $urls[] = $link;
	5088	+ }
	5089	+ $parent = $object->post_parent > 0 ? get_post( (int) $object->post_parent ) : null;
	5090	+ if ( $parent instanceof \WP_Post && 'publish' === $parent->post_status ) {
	5091	+ $parent_link = get_permalink( $parent );
	5092	+ if ( is_string( $parent_link ) && '' !== $parent_link ) {
	5093	+ $urls[] = $parent_link;
	5094	+ }
	5095	+ }
	5096	+ if ( array() !== $urls ) {
	5097	+ self::purge_urls( $urls, 'post-removed:attachment' );
	5098	+ }
	5099	+ return;
	5100	+ }
	5101	+ // Still published here: `before_delete_post` runs before the
	5102	+ // row goes. Trashing reaches the save path instead.
	5103	+ self::purge_post_change( $object, null, 'post-removed:' . $post_type );
	5104	+ return;
	5105	+ }
	5106	+ }
	5107	+
	5108	+ self::purge_all(
	5109	+ 'post-removed:' . $post_type,
	5110	+ null,
	5111	+ array(
	5112	+ 'scope' => 'site',
	5113	+ // Match on_save_post: a presentation type changes how pages
	5114	+ // render rather than what they say.
	5115	+ 'intent' => in_array( $post_type, self::presentation_post_types(), true )
	5116	+ ? 'presentation'
	5117	+ : 'content',
	5118	+ 'urls' => array(),
	5119	+ )
	5120	+ );
	5121	+ }
	5122	+
	5123	+ /** Purge site responses when moderation changes visible comments. */
	5124	+ public static function on_comment_status( $comment_id, $status = '' ): void {
	5125	+ $comment = function_exists( 'get_comment' ) ? get_comment( (int) $comment_id ) : null;
	5126	+ $post_id = is_object( $comment ) && isset( $comment->comment_post_ID ) ? (int) $comment->comment_post_ID : 0;
	5127	+ if ( $post_id < 1 || ! function_exists( 'get_permalink' ) ) {
	5128	+ return;
	5129	+ }
	5130	+ $url = get_permalink( $post_id );
	5131	+ if ( ! is_string( $url ) || '' === $url ) {
	5132	+ return;
	5133	+ }
	5134	+ $post = function_exists( 'get_post' ) ? get_post( $post_id ) : null;
	5135	+ $narrow = $post instanceof \WP_Post && self::narrow_purge_applies( (string) $post->post_type );
	5136	+ if ( $narrow && ! Affected_Pages::site_lists_comments() ) {
	5137	+ $urls = Affected_Pages::for_comment( $post );
	5138	+ if ( array() !== $urls ) {
	5139	+ self::purge_urls( $urls, 'comment-status:' . (string) $status );
	5140	+ }
	5141	+ return;
	5142	+ }
	5143	+ self::purge_all(
	5144	+ 'comment-status:' . (string) $status,
	5145	+ null,
	5146	+ array(
	5147	+ 'scope' => 'site',
	5148	+ 'intent' => 'content',
	5149	+ 'urls' => array(),
	5150	+ // Narrow purges apply to this post, so the site-wide purge is
	5151	+ // for a recent-comments list on pages the rules cannot name.
	5152	+ 'fallback' => $narrow ? self::FALLBACK_THEME_LIST : '',
	5153	+ )
	5154	+ );
	5155	+ }
	5156	+
	5157	+ /**
	5158	+ * comment_post → purge just the commented-on URL, and only once the
	5159	+ * comment is actually visible.
	5160	+ *
	5161	+ * A comment held for moderation changes nothing on the front end, and an
	5162	+ * approved one changes exactly one page — not the whole site. Product
	5163	+ * reviews are comments and guest reviews are on by default, so under the
	5164	+ * old wiring any visitor could flush a store's entire cache, repeatedly,
	5165	+ * with no account. (#243)
	5166	+ *
	5167	+ * @param int $comment_id New comment ID.
	5168	+ * @param int|string $approved 1 when approved, 0 when held, 'spam'.
	5169	+ * @param array $data Comment data.
	5170	+ */
	5171	+ public static function on_comment_post( $comment_id, $approved = 0, $data = array() ): void {
	5172	+ if ( 1 !== (int) $approved ) {
	5173	+ return;
	5174	+ }
	5175	+ $post_id = is_array( $data ) && isset( $data['comment_post_ID'] ) ? (int) $data['comment_post_ID'] : 0;
	5176	+ if ( $post_id < 1 ) {
	5177	+ return;
	5178	+ }
	5179	+ // With narrow purges on, the comment pages and comment feeds go too.
	5180	+ // No site-wide fallback here: a visitor's comment must never be able
	5181	+ // to clear the whole site (#243).
	5182	+ $post = function_exists( 'get_post' ) ? get_post( $post_id ) : null;
	5183	+ if ( $post instanceof \WP_Post && self::narrow_purge_applies( (string) $post->post_type ) ) {
	5184	+ $urls = Affected_Pages::for_comment( $post );
	5185	+ if ( array() !== $urls ) {
	5186	+ self::purge_urls( $urls, 'comment' );
	5187	+ }
	5188	+ return;
	5189	+ }
	5190	+ $url = get_permalink( $post_id );
	5191	+ if ( is_string( $url ) && '' !== $url ) {
	5192	+ self::purge_url( $url, 'comment' );
	5193	+ }
	5194	+ }
	5195	+
	5196	+ /**
	5197	+ * user_register / profile_update → purge only when the user can author
	5198	+ * content that appears on the front end.
	5199	+ *
	5200	+ * A customer registering at checkout changes no rendered page, and cannot
	5201	+ * change an enqueued asset — so it must not purge the cache, and must not
	5202	+ * rebuild the minified bundles. Checkout account-creation fired FOUR
	5203	+ * full-site purges plus four purge_minified() runs in a single request
	5204	+ * before this gate. (#243)
	5205	+ *
	5206	+ * @param int $user_id Affected user.
	5207	+ */
	5208	+ public static function on_user_change( $user_id ): void {
	5209	+ $user = function_exists( 'get_userdata' ) ? get_userdata( (int) $user_id ) : null;
	5210	+ if ( ! $user ) {
	5211	+ return;
	5212	+ }
	5213	+
	5214	+ // Only roles that can publish can change a rendered page. WooCommerce
	5215	+ // customers and WordPress subscribers cannot.
	5216	+ if ( ! user_can( $user, 'edit_posts' ) ) {
	5217	+ return;
	5218	+ }
	5219	+
	5220	+ $url = get_author_posts_url( (int) $user_id );
	5221	+ if ( is_string( $url ) && '' !== $url ) {
	5222	+ self::purge_url( $url, 'user' );
	5223	+ }
	5224	+ }
	5225	+
	5226	+ /**
	5227	+ * Purge everything a product's price / stock / sale state is rendered on.
	5228	+ *
	5229	+ * The product permalink is not enough: the shop archive and the product's
	5230	+ * category and tag archives render the same price and Sale! badge, and
	5231	+ * #242 reproduces all three going stale together.
	5232	+ *
	5233	+ * Accepts a product ID or a WC_Product. A variation resolves to its
	5234	+ * parent, which is the page that actually renders.
	5235	+ *
	5236	+ * @param int|object $product Product ID or WC_Product.
	5237	+ */
	5238	+ public static function purge_product( $product ): void {
	5239	+ $product_id = is_object( $product ) && method_exists( $product, 'get_id' )
	5240	+ ? (int) $product->get_id()
	5241	+ : (int) $product;
	5242	+ if ( $product_id < 1 ) {
	5243	+ return;
	5244	+ }
	5245	+
	5246	+ // Variations are never rendered on their own URL.
	5247	+ $parent = (int) wp_get_post_parent_id( $product_id );
	5248	+ if ( $parent > 0 ) {
	5249	+ $product_id = $parent;
	5250	+ }
	5251	+
	5252	+ // wp-admin's Update saves the product through WooCommerce inside the
	5253	+ // post's own save_post, and Cache::on_save_post() then clears the
	5254	+ // whole site for it, since products are in
	5255	+ // xspeed_site_wide_purge_post_types. Sending these pages first only
	5256	+ // purged them twice. A price or stock change made without a post
	5257	+ // save (an order, the REST API, `$product->save()`) still purges here.
	5258	+ if ( self::site_wide_save_under_way( $product_id ) ) {
	5259	+ return;
	5260	+ }
	5261	+
	5262	+ $urls = array();
	5263	+
	5264	+ $permalink = get_permalink( $product_id );
	5265	+ if ( is_string( $permalink ) && '' !== $permalink ) {
	5266	+ $urls[] = $permalink;
	5267	+ }
	5268	+
	5269	+ // The shop archive.
	5270	+ if ( function_exists( 'wc_get_page_id' ) ) {
	5271	+ $shop_id = (int) wc_get_page_id( 'shop' );
	5272	+ if ( $shop_id > 0 ) {
	5273	+ $shop_url = get_permalink( $shop_id );
	5274	+ if ( is_string( $shop_url ) && '' !== $shop_url ) {
	5275	+ $urls[] = $shop_url;
	5276	+ }
	5277	+ }
	5278	+ }
	5279	+
	5280	+ // Every category / tag archive this product appears on.
	5281	+ foreach ( array( 'product_cat', 'product_tag' ) as $taxonomy ) {
	5282	+ $terms = get_the_terms( $product_id, $taxonomy );
	5283	+ if ( ! is_array( $terms ) ) {
	5284	+ continue;
	5285	+ }
	5286	+ foreach ( $terms as $term ) {
	5287	+ $term_url = get_term_link( $term );
	5288	+ if ( is_string( $term_url ) && '' !== $term_url ) {
	5289	+ $urls[] = $term_url;
	5290	+ }
	5291	+ }
	5292	+ }
	5293	+
	5294	+ // The front page, when it is not the shop page but still lists
	5295	+ // products (a block/shortcode storefront).
	5296	+ $front_id = (int) get_option( 'page_on_front' );
	5297	+ if ( $front_id > 0 ) {
	5298	+ $front_url = get_permalink( $front_id );
	5299	+ if ( is_string( $front_url ) && '' !== $front_url ) {
	5300	+ $urls[] = $front_url;
	5301	+ }
	5302	+ }
	5303	+
	5304	+ /**
	5305	+ * Filter the URLs purged when a product changes.
	5306	+ *
	5307	+ * A storefront that renders products somewhere else — a landing page,
	5308	+ * a custom archive — can add its URLs here rather than falling back
	5309	+ * to purging the whole site.
	5310	+ *
	5311	+ * @param string[] $urls URLs about to be purged.
	5312	+ * @param int $product_id The product that changed.
	5313	+ */
	5314	+ $urls = (array) apply_filters( 'xspeed_purge_product_urls', $urls, $product_id );
	5315	+
	5316	+ $targets = array();
	5317	+ foreach ( $urls as $url ) {
	5318	+ if ( is_scalar( $url ) && '' !== (string) $url ) {
	5319	+ $targets[] = (string) $url;
	5320	+ }
	5321	+ }
	5322	+ if ( array() === $targets ) {
	5323	+ return;
	5324	+ }
	5325	+
	5326	+ // One batch, as a post save sends: one purge-log row and one event
	5327	+ // naming every page, each in the spelling WordPress links to. A
	5328	+ // purge_url() per page published every page in both spellings,
	5329	+ // which doubled the calls to Nginx Helper, and wrote no purge-log
	5330	+ // row when xSpeed's own page cache was off and no file went.
	5331	+ // purge_urls() leaves the object cache alone, which matters here:
	5332	+ // this runs on every stock change at checkout.
	5333	+ self::purge_urls( array_values( array_unique( $targets ) ), 'product', 'content' );
	5334	+ }
	5335	+
	5336	+ /**
	5337	+ * Posts whose save_post is running in this request, keyed by ID, with
	5338	+ * the post as saved. Set before any other save_post listener and cleared
	5339	+ * after the last one.
	5340	+ *
	5341	+ * @var array<int,\WP_Post|null>
	5342	+ */
	5343	+ private static $saves_under_way = array();
	5344	+
	5345	+ /**
	5346	+ * A post save has started.
	5347	+ *
	5348	+ * @param int $post_id Post ID.
	5349	+ * @param \WP_Post|null $post Post as saved.
	5350	+ */
	5351	+ public static function on_post_save_start( $post_id, $post = null ): void {
	5352	+ self::$saves_under_way[ (int) $post_id ] = is_object( $post ) ? $post : null;
	5353	+ }
	5354	+
	5355	+ /**
	5356	+ * A post save has finished.
	5357	+ *
	5358	+ * @param int $post_id Post ID.
	5359	+ */
	5360	+ public static function on_post_save_end( $post_id ): void {
	5361	+ unset( self::$saves_under_way[ (int) $post_id ] );
	5362	+ }
	5363	+
	5364	+ /**
	5365	+ * Whether a save_post for this post is running now and will end in
	5366	+ * on_save_post() clearing the whole site: the same checks it makes.
	5367	+ *
	5368	+ * @param int $post_id Post ID.
	5369	+ */
	5370	+ private static function site_wide_save_under_way( int $post_id ): bool {
	5371	+ if ( ! array_key_exists( $post_id, self::$saves_under_way ) ) {
	5372	+ return false;
	5373	+ }
	5374	+ $post = self::$saves_under_way[ $post_id ];
	5375	+ if ( ! self::post_change_is_cacheable_content( $post_id, $post, 'save' ) ) {
	5376	+ return false;
	5377	+ }
	5378	+ $post_type = is_object( $post ) && isset( $post->post_type )
	5379	+ ? (string) $post->post_type
	5380	+ : (string) get_post_type( $post_id );
	5381	+ if ( in_array( $post_type, self::presentation_post_types(), true ) ) {
	5382	+ return true;
	5383	+ }
	5384	+ return ! self::narrow_purge_applies( $post_type );
	5385	+ }
	5386	+
	5387	+ /** Test seam: forget the post saves in progress. */
	5388	+ public static function reset_saves_under_way(): void {
	5389	+ self::$saves_under_way = array();
	5390	+ }
	5391	+
	5392	+ /**
	5393	+ * Adapter for the WooCommerce stock actions that pass a product OBJECT
	5394	+ * where the status actions pass an ID.
	5395	+ *
	5396	+ * No longer wired to a hook (on_product_stock_set() is); kept because
	5397	+ * it is public.
	5398	+ *
	5399	+ * @param object $product WC_Product (or variation).
	5400	+ */
	5401	+ public static function purge_product_object( $product ): void {
	5402	+ self::purge_product( $product );
	5403	+ }
	5404	+
	5405	+ /**
	5406	+ * Stock writes wc_update_product_stock() has opened in this request,
	5407	+ * keyed by product ID: true once the save inside the write has purged.
	5408	+ *
	5409	+ * Entries are removed when the write's *_set_stock arrives, so this
	5410	+ * holds only writes still in progress.
	5411	+ *
	5412	+ * @var array<int,bool>
	5413	+ */
	5414	+ private static $stock_writes = array();
	5415	+
	5416	+ /**
	5417	+ * A CRUD save of a product: purge its pages.
	5418	+ *
	5419	+ * Inside a wc_update_product_stock() write, this is the save that write
	5420	+ * makes, so note that the write's pages are already purged.
	5421	+ *
	5422	+ * @param int|object $product Product ID (what WooCommerce passes) or WC_Product.
	5423	+ */
	5424	+ public static function on_product_saved( $product ): void {
	5425	+ $product_id = self::product_id_of( $product );
	5426	+ if ( isset( self::$stock_writes[ $product_id ] ) ) {
	5427	+ self::$stock_writes[ $product_id ] = true;
	5428	+ }
	5429	+ self::purge_product( $product );
	5430	+ }
	5431	+
	5432	+ /**
	5433	+ * wc_update_product_stock() is about to write a product's stock.
	5434	+ *
	5435	+ * @param object $product WC_Product (or variation) whose stock changes.
	5436	+ */
	5437	+ public static function on_product_stock_write( $product ): void {
	5438	+ $product_id = self::product_id_of( $product );
	5439	+ if ( $product_id > 0 ) {
	5440	+ self::$stock_writes[ $product_id ] = false;
	5441	+ }
	5442	+ }
	5443	+
	5444	+ /**
	5445	+ * A product's stock changed: purge its pages, unless the save inside
	5446	+ * the same wc_update_product_stock() call already did.
	5447	+ *
	5448	+ * That save fires woocommerce_update_product for the same product a
	5449	+ * moment earlier, with the stock already written, so purging again
	5450	+ * here cleared the same pages twice in one call. Only that pairing is
	5451	+ * skipped: the flag is set by the save inside this write and cleared
	5452	+ * here, so the next write, a status change or a later save in the same
	5453	+ * request purges as usual, and so does a write made with `$updating`
	5454	+ * set, which skips the save. A *_set_stock that arrives without
	5455	+ * *_before_set_stock (WooCommerce's data store fires one mid-save when
	5456	+ * a CRUD save changes the quantity) is not part of a write and purges.
	5457	+ *
	5458	+ * @param object $product WC_Product (or variation).
	5459	+ */
	5460	+ public static function on_product_stock_set( $product ): void {
	5461	+ $product_id = self::product_id_of( $product );
	5462	+ $purged = ! empty( self::$stock_writes[ $product_id ] );
	5463	+ unset( self::$stock_writes[ $product_id ] );
	5464	+ if ( $purged ) {
	5465	+ return;
	5466	+ }
	5467	+ self::purge_product( $product );
	5468	+ }
	5469	+
	5470	+ /** Test seam: forget the stock writes in progress. */
	5471	+ public static function reset_stock_writes(): void {
	5472	+ self::$stock_writes = array();
	5473	+ }
	5474	+
	5475	+ /**
	5476	+ * The ID of a product passed as an ID or as a WC_Product.
	5477	+ *
	5478	+ * @param int|object $product Product ID or WC_Product.
	5479	+ */
	5480	+ private static function product_id_of( $product ): int {
	5481	+ if ( is_object( $product ) ) {
	5482	+ return method_exists( $product, 'get_id' ) ? (int) $product->get_id() : 0;
	5483	+ }
	5484	+ return is_numeric( $product ) ? (int) $product : 0;
	5485	+ }
	5486	+
	5487	+ /**
	5488	+ * Re-entry guard for the purge-event contract.
	5489	+ *
	5490	+ * A listener on `xspeed_after_purge_url` legitimately purges its own
	5491	+ * layer, and a server-cache or CDN adapter that calls back into xSpeed
	5492	+ * while doing so re-enters this method — unbounded, because each pass
	5493	+ * looks like a fresh purge.
	5494	+ *
	5495	+ * A single global flag stops too much: a nested purge of a DIFFERENT URL is
	5496	+ * a real purge whose listeners must hear about it. But a per-request
	5497	+ * "already published" set stops too much in the other direction — a
	5498	+ * network purge loops every blog in one request, and on a subdirectory
	5499	+ * network they share a host, so blogs 2..N would be silently skipped. It
	5500	+ * also grows for the life of the process.
	5501	+ *
	5502	+ * So the guard tracks what is IN FLIGHT, not what has been published: a
	5503	+ * target is marked while its own dispatch is on the stack and unmarked
	5504	+ * when it returns. Re-entering the same target recurses, so it is refused;
	5505	+ * purging the same URL again later is a new event and publishes. The set
	5506	+ * is bounded by call depth rather than by how many URLs a request touches.
	5507	+ *
	5508	+ * @var array<string,bool>
	5509	+ */
	5510	+ private static $purge_events_in_flight = array();
	5511	+
	5512	+ /** Monotonic count used to detect whether a delegated purge published. */
	5513	+ private static $purge_event_sequence = 0;
	5514	+
	5515	+ /**
	5516	+ * Publish a purge event exactly once, with bounded arguments.
	5517	+ *
	5518	+ * Deliberately carries only what an integration needs to invalidate its
	5519	+ * own copy: the canonical URL (or null for a full purge), the site host,
	5520	+ * the cause label, and how many files went. No filesystem paths, no cache
	5521	+ * contents, no request headers, no user data. The URL query and caller-
	5522	+ * supplied cause may nevertheless contain sensitive text, so listeners
	5523	+ * must redact them in logs or unrelated destinations that do not need the
	5524	+ * exact cache key.
	5525	+ *
	5526	+ * A listener that throws must not take the purge down with it: the files
	5527	+ * are already gone by the time we get here, and an integration's bad day
	5528	+ * is not a reason to report a failed purge to the caller.
	5529	+ *
	5530	+ * @param string $hook Hook name to emit.
	5531	+ * @param array<string,mixed> $context Bounded context, see above.
	5532	+ */
	5533	+ private static function dispatch_purge_event( string $hook, array $context ): void {
	5534	+ if ( ! function_exists( 'do_action' ) ) {
	5535	+ return;
	5536	+ }
	5537	+ // Every event carries `fallback`, so one handler can read both the
	5538	+ // per-URL and the full-purge shape. '' unless a narrow purge fell
	5539	+ // back to the whole site.
	5540	+ $context['fallback'] = isset( $context['fallback'] ) && is_string( $context['fallback'] ) ? $context['fallback'] : '';
	5541	+ $target = $hook . '|' . ( isset( $context['url'] ) ? (string) $context['url'] : '' )
	5542	+ . '|' . ( isset( $context['host'] ) ? (string) $context['host'] : '' );
	5543	+ if ( isset( self::$purge_events_in_flight[ $target ] ) ) {
	5544	+ return;
	5545	+ }
	5546	+ self::$purge_events_in_flight[ $target ] = true;
	5547	+ ++self::$purge_event_sequence;
	5548	+
	5549	+ // Our own integrations get their own try. Sharing one with the public
	5550	+ // action below meant a listener on the extension seam could throw and
	5551	+ // take the contract event down with it — the mirror of the failure
	5552	+ // this separation exists to prevent.
	5553	+ try {
	5554	+ // Built-in server-cache integrations run FIRST, and by a direct
	5555	+ // call rather than as listeners on the action below.
	5556	+ //
	5557	+ // WordPress stops dispatching an action's remaining callbacks when
	5558	+ // one of them throws. As a listener, our LiteSpeed forwarding
	5559	+ // would then be skipped by any unrelated third-party callback that
	5560	+ // happened to be registered earlier and blew up — and the visible
	5561	+ // result is the worst kind: xSpeed reports a successful purge while
	5562	+ // the server keeps serving stale HTML. Shipped behaviour must not
	5563	+ // be hostage to a listener's bug.
	5564	+ self::forward_to_server_caches( $context );
	5565	+ } catch ( \Throwable $e ) {
	5566	+ self::log_purge_listener_error( $hook, $e );
	5567	+ }
	5568	+
	5569	+ // The edge xCloud provides, through its purge plugin. Direct for the
	5570	+ // same reason, and in its own try so a failure here cannot cost the
	5571	+ // host page caches above or the public action below.
	5572	+ try {
	5573	+ if ( class_exists( __NAMESPACE__ . '\\Managed_Edge_Purge' ) ) {
	5574	+ Managed_Edge_Purge::forward( $context );
	5575	+ }
	5576	+ } catch ( \Throwable $e ) {
	5577	+ self::log_purge_listener_error( $hook, $e );
	5578	+ }
	5579	+
	5580	+ try {
	5581	+ self::do_action_isolated( $hook, $context );
	5582	+ } catch ( \Throwable $e ) { // phpcs:ignore Generic.CodeAnalysis.EmptyStatement.DetectedCatch
	5583	+ // Swallow: see docblock. The purge succeeded regardless.
	5584	+ self::log_purge_listener_error( $hook, $e );
	5585	+ } finally {
	5586	+ unset( self::$purge_events_in_flight[ $target ] );
	5587	+ }
	5588	+ }
	5589	+
	5590	+ /**
	5591	+ * Run every listener on a purge hook, isolating each from the others.
	5592	+ *
	5593	+ * `do_action()` dispatches callbacks in one loop, so the first one to
	5594	+ * throw takes every LATER listener down with it. On a purge that meant a
	5595	+ * failing CDN integration silently cancelled the ones queued behind it —
	5596	+ * and because the throw was swallowed to keep the purge itself succeeding,
	5597	+ * the user was told the clear worked while two edges were never touched.
	5598	+ * Invisible unless WP_DEBUG happened to be on. (QA #348)
	5599	+ *
	5600	+ * Each callback gets its own try/catch here, so one integration's bad day
	5601	+ * costs only that integration. Priority order is preserved. Falls back to
	5602	+ * a plain `do_action()` when the filter registry is not the shape we
	5603	+ * expect, so an unusual environment degrades to the old behaviour rather
	5604	+ * than skipping listeners entirely.
	5605	+ *
	5606	+ * @param string $hook Hook name to emit.
	5607	+ * @param mixed $arg Single argument passed to each listener.
	5608	+ */
	5609	+ public static function do_action_isolated( string $hook, $arg ): void {
	5610	+ global $wp_filter;
	5611	+
	5612	+ // Walking $wp_filter by hand and calling each callback directly was the
	5613	+ // obvious way to do this, and it was wrong: it bypasses WordPress, so
	5614	+ // `current_filter()` came back empty, `did_action()` stayed at 0, the
	5615	+ // `all` hook never fired, and Query Monitor and Debug Bar could not see
	5616	+ // the very contract this class publishes. A shared handler branching on
	5617	+ // current_filter() picked the wrong branch. (QA #348 round 2, issue 3)
	5618	+ //
	5619	+ // So let do_action() dispatch — WordPress keeps its bookkeeping — and
	5620	+ // isolate one level down instead: each registered callback is swapped
	5621	+ // for a wrapper that runs it inside a try/catch. One listener throwing
	5622	+ // then costs only that listener, which is the whole point, without
	5623	+ // costing the hook its identity.
	5624	+ if ( ! isset( $wp_filter[ $hook ] ) || ! ( $wp_filter[ $hook ] instanceof \WP_Hook ) ) {
	5625	+ do_action( $hook, $arg );
	5626	+ return;
	5627	+ }
	5628	+
	5629	+ $hook_object = $wp_filter[ $hook ];
	5630	+ $original = $hook_object->callbacks;
	5631	+ if ( ! is_array( $original ) || array() === $original ) {
	5632	+ do_action( $hook, $arg );
	5633	+ return;
	5634	+ }
	5635	+
	5636	+ $wrapped = array();
	5637	+ $restorations = array();
	5638	+ foreach ( $original as $priority => $group ) {
	5639	+ if ( ! is_array( $group ) ) {
	5640	+ $wrapped[ $priority ] = $group;
	5641	+ continue;
	5642	+ }
	5643	+ foreach ( $group as $id => $registered ) {
	5644	+ if ( ! isset( $registered['function'] ) || ! is_callable( $registered['function'] ) ) {
	5645	+ $wrapped[ $priority ][ $id ] = $registered;
	5646	+ continue;
	5647	+ }
	5648	+ $callback = $registered['function'];
	5649	+ $wrapper = static function ( ...$args ) use ( $callback, $hook ) {
	5650	+ try {
	5651	+ return $callback( ...$args );
	5652	+ } catch ( \Throwable $e ) {
	5653	+ self::log_purge_listener_error( $hook, $e );
	5654	+ return null;
	5655	+ }
	5656	+ };
	5657	+ $wrapped[ $priority ][ $id ] = array(
	5658	+ // Keep accepted_args: a listener registered for 0 or 1
	5659	+ // arguments must still be called the way it asked.
	5660	+ 'accepted_args' => $registered['accepted_args'] ?? 1,
	5661	+ 'function' => $wrapper,
	5662	+ );
	5663	+ $restorations[ $priority ][ $id ] = array(
	5664	+ 'original' => $registered,
	5665	+ 'wrapper' => $wrapper,
	5666	+ );
	5667	+ }
	5668	+ }
	5669	+
	5670	+ $hook_object->callbacks = $wrapped;
	5671	+ try {
	5672	+ do_action( $hook, $arg );
	5673	+ } finally {
	5674	+ // Restore only wrappers still present. Native add/remove operations
	5675	+ // performed by listeners must survive this temporary substitution.
	5676	+ foreach ( $restorations as $priority => $group ) {
	5677	+ foreach ( $group as $id => $restore ) {
	5678	+ $current = $hook_object->callbacks[ $priority ][ $id ]['function'] ?? null;
	5679	+ if ( $current === $restore['wrapper'] ) {
	5680	+ $hook_object->callbacks[ $priority ][ $id ] = $restore['original'];
	5681	+ }
	5682	+ }
	5683	+ }
	5684	+ }
	5685	+ }
	5686	+
	5687	+ /**
	5688	+ * Name a listener that threw, under WP_DEBUG only.
	5689	+ *
	5690	+ * Gated like the rest of Free's diagnostics: a third-party listener
	5691	+ * throwing on every purge must not fill a production log.
	5692	+ */
	5693	+ private static function log_purge_listener_error( string $hook, \Throwable $e ): void {
	5694	+ // An \Error — a TypeError from one of OUR listeners, say — is a bug
	5695	+ // rather than a runtime condition a third party imposed on us, and
	5696	+ // swallowing it silently in production turns it into a purge that
	5697	+ // quietly stops working. Those are logged whatever WP_DEBUG says;
	5698	+ // third-party \Exceptions stay gated so a noisy integration cannot
	5699	+ // fill a production log.
	5700	+ $always = $e instanceof \Error;
	5701	+ if ( ( $always || ( defined( 'WP_DEBUG' ) && WP_DEBUG ) ) && function_exists( 'error_log' ) ) {
	5702	+ // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- names a third-party listener that threw during a purge.
	5703	+ error_log( '[xspeed] a ' . $hook . ' listener threw: ' . $e->getMessage() );
	5704	+ }
	5705	+ }
	5706	+
	5707	+ /**
	5708	+ * Test seam: clear the in-flight set left behind by an aborted dispatch,
	5709	+ * and the record of which saves purged in this request.
	5710	+ */
	5711	+ public static function reset_purge_events(): void {
	5712	+ self::$purge_events_in_flight = array();
	5713	+ self::$purge_event_sequence = 0;
	5714	+ self::$saves_purged = array();
	5715	+ }
	5716	+
	5717	+ /**
	5718	+ * Hand the purge to the caches we ship integrations for.
	5719	+ *
	5720	+ * Isolated from the public action on purpose — see dispatch_purge_event().
	5721	+ * Guarded so a missing class (a partial upgrade, a stripped build) cannot
	5722	+ * turn a working purge into a fatal.
	5723	+ *
	5724	+ * @param array<string,mixed> $context Bounded purge context.
	5725	+ */
	5726	+ private static function forward_to_server_caches( array $context ): void {
	5727	+ if ( class_exists( __NAMESPACE__ . '\\Server_Caches' ) ) {
	5728	+ Server_Caches::forward( $context );
	5729	+ }
	5730	+ }
	5731	+
	5732	+ /**
	5733	+ * `host[:port]` for a cache key, from a parsed URL.
	5734	+ *
	5735	+ * The port is kept, because `cache_key()` hashes the raw `HTTP_HOST` and
	5736	+ * that carries `:8080` on any install not served from 80/443 — dropping it
	5737	+ * computed a different md5, found no file, and reported "already cold"
	5738	+ * while the page kept serving HIT.
	5739	+ *
	5740	+ * A port that is the DEFAULT for the scheme is dropped, though, because
	5741	+ * `HTTP_HOST` does not carry one: a browser sends `Host: site.com` for
	5742	+ * `https://site.com:443/`. Keeping it hashed `site.com:443` against a file
	5743	+ * stored under `site.com` — the same silent no-op in the other direction,
	5744	+ * and the one QA hit passing a canonical URL with the port spelled out.
	5745	+ * (QA #348)
	5746	+ *
	5747	+ * @param array<string,mixed> $parts Output of wp_parse_url().
	5748	+ */
	5749	+ private static function host_port_of( array $parts ): string {
	5750	+ if ( ! isset( $parts['host'] ) ) {
	5751	+ return '';
	5752	+ }
	5753	+ $host = strtolower( (string) $parts['host'] );
	5754	+ if ( '' === $host || ! isset( $parts['port'] ) ) {
	5755	+ return $host;
	5756	+ }
	5757	+ $port = (int) $parts['port'];
	5758	+ $scheme = isset( $parts['scheme'] ) ? strtolower( (string) $parts['scheme'] ) : '';
	5759	+ if ( ( 'https' === $scheme && 443 === $port ) || ( 'http' === $scheme && 80 === $port ) ) {
	5760	+ return $host;
	5761	+ }
	5762	+ return $host . ':' . $port;
	5763	+ }
	5764	+
	5765	+ public static function purge_url( string $url, string $cause = 'manual' ): int {
	5766	+ // A URL that names nothing is not a purge of everything. An empty or
	5767	+ // blank string used to fall through to the home_url() default below
	5768	+ // and clear the HOMEPAGE — so a third party calling
	5769	+ // `purge_url( get_permalink( $id ) )` on a post whose permalink came
	5770	+ // back empty silently purged the front page instead of nothing. The
	5771	+ // CLI and the MCP tool reject empties before reaching this, so only
	5772	+ // direct API callers were exposed, but they are exactly the audience
	5773	+ // this public contract is for. (QA #348)
	5774	+ if ( '' === trim( $url ) ) {
	5775	+ return 0;
	5776	+ }
	5777	+ // parse_url() can turn raw UTF-8 into underscores (it depends on the
	5778	+ // host's C library and locale), so a pasted `/關於我們/` is encoded
	5779	+ // first. normalize_path() below gives the same result either way.
	5780	+ $url = self::encode_non_ascii( $url );
	5781	+ $parts = function_exists( 'wp_parse_url' ) ? wp_parse_url( $url ) : parse_url( $url ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- fallback for early-boot contexts only.
	5782	+ if ( ! is_array( $parts ) ) {
	5783	+ return 0;
	5784	+ }
	5785	+ // Absolute URLs are accepted only for HTTP response caches. Schemes such
	5786	+ // as ftp:, file: and javascript: can parse cleanly but do not name a page
	5787	+ // xSpeed or a server response cache can invalidate. A leading-slash path
	5788	+ // remains a supported site-relative target.
	5789	+ if ( isset( $parts['scheme'] ) && ! in_array( strtolower( (string) $parts['scheme'] ), array( 'http', 'https' ), true ) ) {
	5790	+ return 0;
	5791	+ }
	5792	+ if ( isset( $parts['scheme'] ) && empty( $parts['host'] ) ) {
	5793	+ return 0;
	5794	+ }
	5795	+ // Reject a string that parsed but is not a URL we can act on: no
	5796	+ // scheme AND no host AND no leading-slash path means something like
	5797	+ // `ht!tp://[[[` or a bare word, which parse_url() hands back as a
	5798	+ // relative "path". Forwarding that produced `purge_url(/ht!tp://[[[)`
	5799	+ // — a nonsense tag sent to LiteSpeed for every malformed call.
	5800	+ if ( ! isset( $parts['scheme'] ) && ! isset( $parts['host'] ) ) {
	5801	+ $raw = isset( $parts['path'] ) ? (string) $parts['path'] : '';
	5802	+ if ( '' === $raw || '/' !== $raw[0] ) {
	5803	+ return 0;
	5804	+ }
	5805	+ }
	5806	+ // Keep the port. `cache_key()` hashes the raw `HTTP_HOST`, which
	5807	+ // carries `:8080` on any install not served from 80/443 — while
	5808	+ // parse_url() splits the port into its own component, so a purge that
	5809	+ // used the bare host computed a different md5, found no file, and
	5810	+ // reported "already cold". A silent no-op: the page kept serving HIT
	5811	+ // until its TTL ran out. Intranet installs, panel hosts on :8443 and
	5812	+ // proxies that forward `Host: site.com:8080` all hit this.
	5813	+ // A scheme-less `site.test:443/page/` is a supported explicit-host
	5814	+ // target. Infer a scheme only when it names THIS site's hostname: then
	5815	+ // its explicit default port is the same origin and the same local cache
	5816	+ // key. Never apply this to another host or to a non-default port.
	5817	+ if ( ! isset( $parts['scheme'] ) && isset( $parts['host'], $parts['port'] ) && function_exists( 'home_url' ) ) {
	5818	+ $home = function_exists( 'wp_parse_url' ) ? wp_parse_url( home_url( '/' ) ) : parse_url( home_url( '/' ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- see above.
	5819	+ if ( is_array( $home ) && ! empty( $home['host'] ) && ! empty( $home['scheme'] )
	5820	+ && strtolower( (string) $home['host'] ) === strtolower( (string) $parts['host'] )
	5821	+ ) {
	5822	+ $home_scheme = strtolower( (string) $home['scheme'] );
	5823	+ $port = (int) $parts['port'];
	5824	+ $home_port = isset( $home['port'] )
	5825	+ ? (int) $home['port']
	5826	+ : ( 'https' === $home_scheme ? 443 : ( 'http' === $home_scheme ? 80 : 0 ) );
	5827	+ if ( $home_port === $port
	5828	+ && ( ( 'https' === $home_scheme && 443 === $port ) || ( 'http' === $home_scheme && 80 === $port ) )
	5829	+ ) {
	5830	+ $parts['scheme'] = $home_scheme;
	5831	+ }
	5832	+ }
	5833	+ }
	5834	+ $host = self::host_port_of( $parts );
	5835	+ if ( '' === $host && function_exists( 'home_url' ) ) {
	5836	+ $home = function_exists( 'wp_parse_url' ) ? wp_parse_url( home_url( '/' ) ) : parse_url( home_url( '/' ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- see above.
	5837	+ if ( is_array( $home ) ) {
	5838	+ $host = self::host_port_of( $home );
	5839	+ }
	5840	+ }
	5841	+ if ( '' === $host ) {
	5842	+ return 0;
	5843	+ }
	5844	+ $path = isset( $parts['path'] ) ? (string) $parts['path'] : '/';
	5845	+ $path = '/' . ltrim( $path, '/' );
	5846	+ if ( false !== strpos( $path, '..' ) ) {
	5847	+ return 0;
	5848	+ }
	5849	+ // Same spelling cache_key() hashes, so a permalink, the same URL with
	5850	+ // `%E7` capitals, and a pasted `/關於我們/` all find the entry. The
	5851	+ // purge event below keeps the caller's spelling and adds the others
	5852	+ // (see escape_spellings()).
	5853	+ $key_path = self::normalize_path( $path );
	5854	+
	5855	+ // The cache key preserves REQUEST_URI's trailing-slash form, so
	5856	+ // purge both. Root stays a single '/'.
	5857	+ $forms = array( $key_path );
	5858	+ if ( '/' !== $key_path ) {
	5859	+ $forms[] = rtrim( $key_path, '/' );
	5860	+ $forms[] = rtrim( $key_path, '/' ) . '/';
	5861	+ }
	5862	+ $forms = array_unique( $forms );
	5863	+
	5864	+ /*
	5865	+ * Entries live under the bucket they were written for, and this URL's
	5866	+ * site may not be the one serving THIS request (a cross-site purge on
	5867	+ * multisite, WP-CLI, or cron). Build the directory from the URL's own
	5868	+ * host AND path. (#6)
	5869	+ *
	5870	+ * Host alone is wrong on a subdirectory network: `store()` wrote to
	5871	+ * `<host>/<prefix>/`, so looking in `<host>/` found nothing and the
	5872	+ * call reported "already cold" while the page kept serving HIT — a
	5873	+ * false success, which is worse than an error. The prefix has to come
	5874	+ * from the URL being purged rather than from the current blog, because
	5875	+ * the caller is usually purging some OTHER site. (QA B2 on #166)
	5876	+ */
	5877	+ $base = XSPEED_CACHE_DIR . '/' . self::bucket_for_url( $host, $path );
	5878	+
850	5879	$count = 0;
851		- if ( is_dir( XSPEED_CACHE_DIR ) ) {
852		- $files = glob( XSPEED_CACHE_DIR . '/*.html' );
853		- if ( $files ) {
854		- $count = count( $files );
855		- foreach ( $files as $f ) {
856		- wp_delete_file( $f );
	5880	+ foreach ( $forms as $uri ) {
	5881	+ // '' = mobile_separate off; '|m' / '|d' = the device buckets.
	5882	+ foreach ( array( '', '|m', '|d' ) as $device ) {
	5883	+ $key = md5( $host . $uri . $device );
	5884	+ $file = $base . '/' . $key . '.html';
	5885	+ if ( is_file( $file ) ) {
	5886	+ wp_delete_file( $file );
	5887	+ ++$count;
857	5888	}
	5889	+ foreach ( array( $base . '/' . $key . '.meta', $file . '.br', self::brotli_size_sidecar( $file . '.br' ) ) as $sidecar ) {
	5890	+ if ( is_file( $sidecar ) ) {
	5891	+ wp_delete_file( $sidecar );
	5892	+ }
	5893	+ }
858	5894	}
859		- // Remove the .meta sidecars (content-type for feeds/sitemaps)
860		- // alongside their .html entries. Not counted — they're not
861		- // cache "pages", just per-entry metadata.
862		- $meta = glob( XSPEED_CACHE_DIR . '/*.meta' );
863		- if ( $meta ) {
864		- foreach ( $meta as $m ) {
865		- wp_delete_file( $m );
	5895	+ }
	5896	+
	5897	+ // Static tree (served directly by the nginx/.htaccess rewrite).
	5898	+ // The static tree stores decoded names (see static_path()). A path
	5899	+ // static_path() refuses was never written there.
	5900	+ $rel = self::static_path( $key_path );
	5901	+ if ( defined( 'XSPEED_CACHE_STATIC_DIR' ) && null !== $rel ) {
	5902	+ // Same transform the write used — `localhost:8080` files under
	5903	+ // `localhost8080`, so the bare host found nothing here either.
	5904	+ $dir = rtrim( XSPEED_CACHE_STATIC_DIR, '/' ) . '/' . self::static_host_dir( $host ) . $rel;
	5905	+ $file = $dir . '/index.html';
	5906	+ if ( is_file( $file ) ) {
	5907	+ wp_delete_file( $file );
	5908	+ ++$count;
	5909	+ }
	5910	+ foreach ( array( $file . '.br', self::brotli_size_sidecar( $file . '.br' ) ) as $sidecar ) {
	5911	+ if ( is_file( $sidecar ) ) {
	5912	+ wp_delete_file( $sidecar );
866	5913	}
867	5914	}
868		- // Remove precompressed siblings (e.g. <key>.html.br from the Pro
869		- // Brotli module). Not counted — same as .meta. Without this a
870		- // purge leaves stale .br bodies behind: disk bloat, and a
871		- // staleness window if precompression is later disabled.
872		- $br = glob( XSPEED_CACHE_DIR . '/*.br' );
873		- if ( $br ) {
874		- foreach ( $br as $b ) {
875		- wp_delete_file( $b );
	5915	+ }
	5916	+
	5917	+ /*
	5918	+ * The per-URL purge event is published by `dispatch_purge_event()`
	5919	+ * below, NOT here.
	5920	+ *
	5921	+ * This branch used to publish it itself, with a raw `do_action` and a
	5922	+ * `{scope,url,urls,cause,count}` payload. #348 then landed the purge
	5923	+ * contract on dev: a canonical URL, `removed` rather than `count`,
	5924	+ * `intent`, per-listener isolation, and an in-flight guard so a
	5925	+ * listener that purges its own layer cannot re-enter the event.
	5926	+ *
	5927	+ * Keeping both meant every per-URL purge fired TWICE, in two payload
	5928	+ * shapes, and the raw call bypassed the guard — so a listener that
	5929	+ * called back into `purge_url()` recursed until the process ran out
	5930	+ * of memory. `CachePurgeEventContractTest::
	5931	+ * test_a_listener_re_purging_the_same_url_does_not_recurse` is what
	5932	+ * caught it, and it arrived from dev with the contract it defends.
	5933	+ *
	5934	+ * The contract wins: it is a superset of what this published, and it
	5935	+ * is what the LiteSpeed and nginx adapters are written against.
	5936	+ */
	5937	+
	5938	+ // purge_url_reported() writes this row itself once the event has
	5939	+ // gone out, so it can name the caches the purge was sent to.
	5940	+ if ( $count > 0 && null === self::$url_batch && null === self::$reported_url_purge ) {
	5941	+ Cache_Inventory::invalidate();
	5942	+ Activity_Log::record(
	5943	+ 'cache_purge_url',
	5944	+ sprintf(
	5945	+ /* translators: 1: cause of the purge, 2: URL or path, 3: number of files removed. */
	5946	+ __( 'Purged one URL (%1$s) — %2$s, %3$d file(s) removed', 'xspeed' ),
	5947	+ $cause,
	5948	+ $host . $path,
	5949	+ $count
	5950	+ ),
	5951	+ Activity_Log::INFO
	5952	+ );
	5953	+ }
	5954	+
	5955	+ /**
	5956	+ * Fires after one URL's cached copy has been purged.
	5957	+ *
	5958	+ * The single-URL counterpart to `xspeed_after_purge_all`. Subscribe
	5959	+ * here to invalidate a cache xSpeed does not own — a server-level
	5960	+ * cache such as LiteSpeed's LSCache, a reverse proxy, or a CDN — for
	5961	+ * the same URL.
	5962	+ *
	5963	+ * Only fires when the purge actually ran. A malformed URL, a URL with
	5964	+ * no resolvable host, or a traversal attempt returns earlier and
	5965	+ * publishes nothing, so a listener can treat this as "xSpeed purged
	5966	+ * this URL" rather than "xSpeed was asked to". `removed` may legitimately
	5967	+ * be 0: the URL was not in xSpeed's cache, which says nothing about
	5968	+ * whether it is in yours.
	5969	+ *
	5970	+ * Fires at most once per purge. A listener that calls back into
	5971	+ * xSpeed's purge API will not re-enter this event.
	5972	+ *
	5973	+ * @since 1.2.3
	5974	+ *
	5975	+ * @param array $context {
	5976	+ * Bounded description of the purge. URL queries and caller-supplied
	5977	+ * causes can contain sensitive values and are not logging fields.
	5978	+ *
	5979	+ * @type string $url Canonical scheme://host/path[?query] of the purged URL.
	5980	+ * The query is preserved because caches in front
	5981	+ * commonly key on it; xSpeed's own sweep is
	5982	+ * path-based, so `removed` describes that.
	5983	+ * @type string $host Host (with port when non-standard).
	5984	+ * @type string $path Path component, leading slash.
	5985	+ * @type string $cause Short label for who asked. See purge_all().
	5986	+ * @type int $removed Number of cache files removed.
	5987	+ * @type string $scope Actionable adapter scope: `urls`.
	5988	+ * @type string $intent Why responses changed: `content`.
	5989	+ * @type string[] $urls Exact response URLs to invalidate: the
	5990	+ * canonical URL first, then the same URL
	5991	+ * with the other trailing-slash spelling
	5992	+ * (none for the root). A path with
	5993	+ * percent-escapes adds the same pair with
	5994	+ * the escapes in lower case and in upper
	5995	+ * case, where those differ from it.
	5996	+ * @type string $fallback Always '' on this event. Present so both
	5997	+ * purge events share one shape; see
	5998	+ * `xspeed_after_purge`.
	5999	+ * }
	6000	+ */
	6001	+ $query = isset( $parts['query'] ) ? (string) $parts['query'] : '';
	6002	+ $url_scheme = isset( $parts['scheme'] ) ? strtolower( (string) $parts['scheme'] ) : '';
	6003	+ $canonical_url = self::canonical_purge_url( $host, $path, $query, $url_scheme );
	6004	+ // Every spelling the local sweep above cleared, because a cache in
	6005	+ // front keys each one on its own. Visitors reach a page as `/about/`
	6006	+ // while a caller often passes `/about` (or the reverse), and a
	6007	+ // non-ASCII page as `/%E9%97%9C…/` while get_permalink() passes
	6008	+ // `/%e9%97%9c…/`. Publishing one spelling left the edge serving the
	6009	+ // other, usually the one visitors actually use.
	6010	+ $event_urls = array();
	6011	+ foreach ( self::escape_spellings( $path ) as $spelling ) {
	6012	+ $event_urls[] = self::canonical_purge_url( $host, $spelling, $query, $url_scheme );
	6013	+ if ( '/' === $spelling ) {
	6014	+ continue;
	6015	+ }
	6016	+ $other = '/' === substr( $spelling, -1 ) ? rtrim( $spelling, '/' ) : $spelling . '/';
	6017	+ if ( '' !== $other ) {
	6018	+ $event_urls[] = self::canonical_purge_url( $host, $other, $query, $url_scheme );
	6019	+ }
	6020	+ }
	6021	+ // Inside purge_urls(): the batch publishes one event for every URL,
	6022	+ // in the trailing-slash form it was given. The local sweep above still
	6023	+ // took both forms. Escape spellings are still added, because the other
	6024	+ // escape case does not redirect: a cache in front keeps the browser's
	6025	+ // `%E9…` copy apart from the permalink's `%e9…` one.
	6026	+ if ( null !== self::$url_batch ) {
	6027	+ if ( '' === self::$url_batch['url'] ) {
	6028	+ self::$url_batch['url'] = $canonical_url;
	6029	+ self::$url_batch['host'] = $host;
	6030	+ self::$url_batch['path'] = $path;
	6031	+ }
	6032	+ self::$url_batch['removed'] += $count;
	6033	+ foreach ( self::escape_spellings( $path ) as $spelling ) {
	6034	+ self::$url_batch['urls'][ self::canonical_purge_url( $host, $spelling, $query, $url_scheme ) ] = true;
	6035	+ }
	6036	+ return $count;
	6037	+ }
	6038	+
	6039	+ self::dispatch_purge_event(
	6040	+ 'xspeed_after_purge_url',
	6041	+ array(
	6042	+ 'url' => $canonical_url,
	6043	+ 'host' => $host,
	6044	+ 'path' => $path,
	6045	+ 'cause' => $cause,
	6046	+ 'removed' => $count,
	6047	+ 'scope' => 'urls',
	6048	+ 'intent' => 'content',
	6049	+ 'urls' => array_values( array_unique( $event_urls ) ),
	6050	+ 'fallback' => '',
	6051	+ )
	6052	+ );
	6053	+
	6054	+ return $count;
	6055	+ }
	6056	+
	6057	+ /**
	6058	+ * The batch purge_urls() is collecting, or null outside one.
	6059	+ *
	6060	+ * @var array{url:string,host:string,path:string,removed:int,urls:array<string,bool>}|null
	6061	+ */
	6062	+ private static $url_batch = null;
	6063	+
	6064	+ /**
	6065	+ * The caches in front of PHP that took a purge while a report is open,
	6066	+ * keyed by label, or null when no report is open.
	6067	+ *
	6068	+ * @var array<string,bool>|null
	6069	+ */
	6070	+ private static $forward_report = null;
	6071	+
	6072	+ /**
	6073	+ * Note that a purge was handed to a cache in front of PHP: a server
	6074	+ * cache, a host cache, a CDN or an edge.
	6075	+ *
	6076	+ * The built-in adapters call this when they accept a purge, whether
	6077	+ * they send it now or queue it for the end of the request. A third-party
	6078	+ * adapter listening on `xspeed_after_purge_url` may call it too, so an
	6079	+ * operator's purge names it. Does nothing unless a caller opened a
	6080	+ * report with purge_url_reported().
	6081	+ *
	6082	+ * @param string $layer Name to show, such as "Nginx Helper".
	6083	+ */
	6084	+ public static function note_purge_forwarded( string $layer ): void {
	6085	+ if ( null === self::$forward_report || '' === trim( $layer ) ) {
	6086	+ return;
	6087	+ }
	6088	+ self::$forward_report[ $layer ] = true;
	6089	+ }
	6090	+
	6091	+ /**
	6092	+ * Run a purge and collect the caches in front of PHP it was sent to.
	6093	+ *
	6094	+ * @param callable $purge The purge to run.
	6095	+ * @return array{result:mixed,forwarded:string[]}
	6096	+ */
	6097	+ public static function report_forwarding( callable $purge ): array {
	6098	+ $outer = self::$forward_report;
	6099	+ self::$forward_report = array();
	6100	+ try {
	6101	+ $result = $purge();
	6102	+ } finally {
	6103	+ $forwarded = array_keys( (array) self::$forward_report );
	6104	+ self::$forward_report = null === $outer ? null : $outer + (array) self::$forward_report;
	6105	+ }
	6106	+ return array(
	6107	+ 'result' => $result,
	6108	+ 'forwarded' => $forwarded,
	6109	+ );
	6110	+ }
	6111	+
	6112	+ /**
	6113	+ * Set while purge_url_reported() runs, so purge_url() leaves the
	6114	+ * purge-log row to it. Null otherwise.
	6115	+ *
	6116	+ * @var bool|null
	6117	+ */
	6118	+ private static $reported_url_purge = null;
	6119	+
	6120	+ /**
	6121	+ * Purge one URL for an operator, and say where the purge went.
	6122	+ *
	6123	+ * purge_url() writes a purge-log row only when it removed a local file,
	6124	+ * because Pro's beacons call it on visitor requests. On a site whose
	6125	+ * pages are held only by a server cache (xSpeed's page cache off, nginx
	6126	+ * in front) an operator's purge then removed nothing locally, was sent
	6127	+ * to the server cache, and left no row and an "already cold" answer.
	6128	+ * This adds the row in that case. The CLI, the MCP tool (which runs the
	6129	+ * CLI) and the admin "Purge this URL" link use it.
	6130	+ *
	6131	+ * @param string $url Absolute URL or site-relative path.
	6132	+ * @param string $cause Who asked, for the purge log.
	6133	+ * @return array{removed:int,forwarded:string[]} Files removed here, and
	6134	+ * the caches the purge was sent to.
	6135	+ */
	6136	+ public static function purge_url_reported( string $url, string $cause ): array {
	6137	+ $outer = self::$reported_url_purge;
	6138	+ self::$reported_url_purge = true;
	6139	+ try {
	6140	+ $run = self::report_forwarding(
	6141	+ static function () use ( $url, $cause ): int {
	6142	+ return self::purge_url( $url, $cause );
876	6143	}
	6144	+ );
	6145	+ } finally {
	6146	+ self::$reported_url_purge = $outer;
	6147	+ }
	6148	+ $removed = (int) $run['result'];
	6149	+ $forwarded = $run['forwarded'];
	6150	+
	6151	+ if ( $removed > 0 ) {
	6152	+ Cache_Inventory::invalidate();
	6153	+ $message = array() === $forwarded
	6154	+ ? sprintf(
	6155	+ /* translators: 1: cause of the purge, 2: URL or path, 3: number of files removed. */
	6156	+ __( 'Purged one URL (%1$s) — %2$s, %3$d file(s) removed', 'xspeed' ),
	6157	+ $cause,
	6158	+ $url,
	6159	+ $removed
	6160	+ )
	6161	+ : sprintf(
	6162	+ /* translators: 1: cause of the purge, 2: URL or path, 3: number of files removed, 4: caches the purge was sent to. */
	6163	+ __( 'Purged one URL (%1$s) — %2$s, %3$d file(s) removed, sent to %4$s', 'xspeed' ),
	6164	+ $cause,
	6165	+ $url,
	6166	+ $removed,
	6167	+ implode( ', ', $forwarded )
	6168	+ );
	6169	+ Activity_Log::record( 'cache_purge_url', $message, Activity_Log::INFO );
	6170	+ } elseif ( array() !== $forwarded ) {
	6171	+ Activity_Log::record(
	6172	+ 'cache_purge_url',
	6173	+ sprintf(
	6174	+ /* translators: 1: cause of the purge, 2: URL or path, 3: caches the purge was sent to. */
	6175	+ __( 'Purged one URL (%1$s): %2$s, 0 file(s) removed here, sent to %3$s', 'xspeed' ),
	6176	+ $cause,
	6177	+ $url,
	6178	+ implode( ', ', $forwarded )
	6179	+ ),
	6180	+ Activity_Log::INFO
	6181	+ );
	6182	+ }
	6183	+
	6184	+ return array(
	6185	+ 'removed' => $removed,
	6186	+ 'forwarded' => $forwarded,
	6187	+ );
	6188	+ }
	6189	+
	6190	+ /**
	6191	+ * Purge several URLs as one purge: each URL's local copy goes as in
	6192	+ * purge_url(), then ONE `xspeed_after_purge_url` event carries every URL.
	6193	+ *
	6194	+ * One event rather than one per URL, so the purge log gets one line, an
	6195	+ * edge gets one batch, and a listener that counts purges counts one. The
	6196	+ * event is the same contract purge_url() publishes: `scope` is `urls`,
	6197	+ * `url` is the first URL, `urls` is all of them.
	6198	+ *
	6199	+ * Unlike purge_url(), `urls` holds each URL in the spelling it was given
	6200	+ * and not the other trailing-slash spelling too. Callers pass WordPress's
	6201	+ * own links (get_permalink(), get_term_link() and the like), which are
	6202	+ * the spelling visitors reach; the other spelling redirects to it, so a
	6203	+ * cache in front holds nothing stale under it. Both spellings doubled the
	6204	+ * list: a typical save named 34 pages as 67 URLs, past xCloud's 50-URL
	6205	+ * batch and the Hub's 30 per call. xSpeed's own sweep still removes both
	6206	+ * spellings of each. The escape spellings (escape_spellings()) are still
	6207	+ * listed, because `%E9…` does not redirect to `%e9…`; they add URLs only
	6208	+ * for a path with percent-escapes.
	6209	+ *
	6210	+ * The object cache is left alone, as purge_url() leaves it. WordPress
	6211	+ * already drops a post's own entries when the post, its terms or its
	6212	+ * comments change (clean_post_cache() and the like), so a flush here
	6213	+ * cleared nothing stale. What it did do: an approved visitor comment
	6214	+ * emptied Redis or Memcached for the whole site, as often as a visitor
	6215	+ * cared to comment. With a persistent object cache, transients live
	6216	+ * there too, so a flush could also drop work a purge listener had just
	6217	+ * queued in one. purge_all() still flushes.
	6218	+ *
	6219	+ * @param string[] $urls Absolute URLs or site-relative paths.
	6220	+ * @param string $cause Who asked, for the purge log.
	6221	+ * @param string $intent Why responses changed: `content` by default.
	6222	+ * @return int Cache files removed.
	6223	+ */
	6224	+ public static function purge_urls( array $urls, string $cause = 'manual', string $intent = 'content' ): int {
	6225	+ $outer = self::$url_batch;
	6226	+ self::$url_batch = array(
	6227	+ 'url' => '',
	6228	+ 'host' => '',
	6229	+ 'path' => '',
	6230	+ 'removed' => 0,
	6231	+ 'urls' => array(),
	6232	+ );
	6233	+ try {
	6234	+ foreach ( array_unique( array_filter( $urls, 'is_string' ) ) as $url ) {
	6235	+ self::purge_url( $url, $cause );
877	6236	}
	6237	+ } finally {
	6238	+ $batch = self::$url_batch;
	6239	+ self::$url_batch = $outer;
878	6240	}
	6241	+ if ( '' === $batch['url'] ) {
	6242	+ return 0;
	6243	+ }
	6244	+
	6245	+ Cache_Inventory::invalidate();
	6246	+ self::update_stats( array( 'last_purge' => time() ) );
	6247	+ // Same type as one URL's purge, so the purge log and the dashboard's
	6248	+ // drill-down list it with the others.
	6249	+ Activity_Log::record(
	6250	+ 'cache_purge_url',
	6251	+ sprintf(
	6252	+ /* translators: 1: number of pages, 2: cause of the purge, 3: number of files removed. */
	6253	+ _n( 'Purged %1$d page (%2$s), %3$d file(s) removed', 'Purged %1$d pages (%2$s), %3$d file(s) removed', count( $urls ), 'xspeed' ),
	6254	+ count( $urls ),
	6255	+ $cause,
	6256	+ $batch['removed']
	6257	+ ),
	6258	+ Activity_Log::INFO
	6259	+ );
	6260	+
	6261	+ self::dispatch_purge_event(
	6262	+ 'xspeed_after_purge_url',
	6263	+ array(
	6264	+ 'url' => $batch['url'],
	6265	+ 'host' => $batch['host'],
	6266	+ 'path' => $batch['path'],
	6267	+ 'cause' => $cause,
	6268	+ 'removed' => $batch['removed'],
	6269	+ 'scope' => 'urls',
	6270	+ 'intent' => $intent,
	6271	+ 'urls' => array_keys( $batch['urls'] ),
	6272	+ 'fallback' => '',
	6273	+ )
	6274	+ );
	6275	+
	6276	+ return $batch['removed'];
	6277	+ }
	6278	+
	6279	+ /** Host this site's purge is scoped to, for the purge-event context. */
	6280	+ private static function current_purge_host(): string {
	6281	+ if ( ! function_exists( 'home_url' ) ) {
	6282	+ return '';
	6283	+ }
	6284	+ $home = function_exists( 'wp_parse_url' ) ? wp_parse_url( home_url( '/' ) ) : parse_url( home_url( '/' ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- host only.
	6285	+ if ( ! is_array( $home ) || empty( $home['host'] ) ) {
	6286	+ return '';
	6287	+ }
	6288	+ // Same default-port normalisation as purge_url(): a site whose
	6289	+ // home_url() carries `:443` (normal behind a proxy) otherwise stamps
	6290	+ // every full-purge event with a host that matches none of its own
	6291	+ // URLs, so the LiteSpeed forward stood down site-wide. (QA #348)
	6292	+ return self::host_port_of( $home );
	6293	+ }
	6294	+
	6295	+ /**
	6296	+ * Rebuild the canonical URL a purge applied to.
	6297	+ *
	6298	+ * Built from the parts the purge itself used, so a listener is told the
	6299	+ * URL we acted on rather than the string the caller happened to pass —
	6300	+ * those differ whenever the caller supplied a site-relative path, a
	6301	+ * different scheme, or a query string the cache key ignores.
	6302	+ */
	6303	+ private static function canonical_purge_url( string $host, string $path, string $query = '', string $url_scheme = '' ): string {
	6304	+ // The purged URL's own scheme wins. purge_url() explicitly supports
	6305	+ // cross-site purges (multisite, WP-CLI, cron), where composing the
	6306	+ // current site's scheme onto another site's host builds a URL that was
	6307	+ // never served — and a CDN listener then purges the wrong key and
	6308	+ // reports success.
	6309	+ if ( '' !== $url_scheme ) {
	6310	+ return $url_scheme . '://' . $host . $path . ( '' !== $query ? '?' . $query : '' );
	6311	+ }
	6312	+ $scheme = function_exists( 'is_ssl' ) && is_ssl() ? 'https' : 'http';
	6313	+ if ( function_exists( 'home_url' ) ) {
	6314	+ $home = function_exists( 'wp_parse_url' ) ? wp_parse_url( home_url( '/' ) ) : parse_url( home_url( '/' ) ); // phpcs:ignore WordPress.WP.AlternativeFunctions.parse_url_parse_url -- scheme only.
	6315	+ if ( is_array( $home ) && ! empty( $home['scheme'] ) ) {
	6316	+ $scheme = (string) $home['scheme'];
	6317	+ }
	6318	+ }
	6319	+ // The query is carried even though OUR sweep above is path-based.
	6320	+ // Caches in front commonly key on the full request line — LiteSpeed
	6321	+ // tags `/shop/?page=2` separately from `/shop/` — so publishing the
	6322	+ // bare path would have a listener confidently purge the wrong entry
	6323	+ // and report success. Telling it exactly what was asked for lets it
	6324	+ // act correctly; `removed` still describes only what WE removed.
	6325	+ return $scheme . '://' . $host . $path . ( '' !== $query ? '?' . $query : '' );
	6326	+ }
	6327	+
	6328	+ /**
	6329	+ * Sweep this site's cache files.
	6330	+ *
	6331	+ * On multisite every blog shares one cache directory, so an unscoped
	6332	+ * sweep here took the whole network cold — one subsite's settings save
	6333	+ * or post publish rebuilt every other site from PHP. Entries are stored
	6334	+ * per host (see host_dir()), and the sweep is scoped to match, so a
	6335	+ * purge originating on site-a leaves site-b's cache warm. (#6)
	6336	+ *
	6337	+ * Clears the files only: the flat tree, the static tree, the REST
	6338	+ * responses and the minified assets. The object-cache flush, the stats
	6339	+ * update, `xspeed_after_purge_all`, the `xspeed_after_purge` contract
	6340	+ * event and the log entry live in purge_all(), which is still the entry
	6341	+ * point for every existing caller. Split out so `wp xspeed purge` can
	6342	+ * report the local sweep as one line item and the object cache as
	6343	+ * another, each with its own status — see Purge_Runner.
	6344	+ *
	6345	+ * @param string|null $host Host to purge. Defaults to the current site.
	6346	+ * Pass '*' to sweep the ENTIRE tree — network
	6347	+ * admin's "purge all sites", and the migration
	6348	+ * of pre-#6 entries that sit in the tree root.
	6349	+ * @return array{pages:int,rest:int,assets:int,bytes:int} Entries removed
	6350	+ * per store, and the bytes freed by the two file sweeps
	6351	+ * that measure themselves.
	6352	+ */
	6353	+ public static function purge_local( ?string $host = null ): array {
	6354	+ $network_wide = ( '*' === $host );
	6355	+ self::$sweep_bytes = 0;
	6356	+ // The flat tree buckets by a flattened segment (host/a-b) while the
	6357	+ // static tree mirrors the URL (host/a/b), so they need separate
	6358	+ // scopes — see current_host_dir() vs current_static_scope().
	6359	+ $static_scope = '';
	6360	+ if ( null === $host || $network_wide ) {
	6361	+ $scope = $network_wide ? '' : self::current_host_dir();
	6362	+ $static_scope = $network_wide ? '' : self::current_static_scope();
	6363	+ } else {
	6364	+ $dir = self::host_dir( $host );
	6365	+ $scope = '' === $dir ? 'default' : $dir;
	6366	+ $static_dir = self::static_host_dir( $host );
	6367	+ $static_scope = '' === $static_dir ? 'default' : $static_dir;
	6368	+ }
	6369	+
	6370	+ $count = 0;
	6371	+ if ( is_dir( XSPEED_CACHE_DIR ) ) {
	6372	+ // Scoped to one host directory, or the whole tree (including the
	6373	+ // legacy top-level entries written before #6) when network-wide.
	6374	+ /*
	6375	+ * Network-wide sweeps go TWO levels deep, not one. A subdirectory
	6376	+ * subsite's bucket is `<host>/<prefix>/`, so globbing only
	6377	+ * `<cache>/*` reached the main site and left every subsite's
	6378	+ * entries in place. (QA D5 on #166)
	6379	+ *
	6380	+ * A scoped purge also has to cover its own nested buckets: when
	6381	+ * the main blog of a subdirectory network purges, `<host>/` is its
	6382	+ * bucket and `<host>/one/` belongs to another blog — so the scoped
	6383	+ * branch deliberately does NOT descend, which is what keeps
	6384	+ * site-level purges isolated.
	6385	+ */
	6386	+ $roots = $network_wide
	6387	+ ? array_merge(
	6388	+ array( XSPEED_CACHE_DIR ),
	6389	+ array_filter( (array) glob( XSPEED_CACHE_DIR . '/*', GLOB_ONLYDIR ) ),
	6390	+ array_filter( (array) glob( XSPEED_CACHE_DIR . '/*/*', GLOB_ONLYDIR ) )
	6391	+ )
	6392	+ : array( XSPEED_CACHE_DIR . '/' . $scope );
	6393	+
	6394	+ foreach ( $roots as $root ) {
	6395	+ /*
	6396	+ * min/ and rest/ are swept by their own purgers below; never
	6397	+ * treat them as host buckets.
	6398	+ *
	6399	+ * Checked on every path SEGMENT, not just the basename: now
	6400	+ * that the network-wide glob descends two levels it can reach
	6401	+ * `min/combined`, whose basename is `combined` and would sail
	6402	+ * past a basename-only test — deleting the combined
	6403	+ * stylesheets out from under the pages that link them.
	6404	+ */
	6405	+ if ( ! $network_wide || XSPEED_CACHE_DIR !== $root ) {
	6406	+ $relative = trim( str_replace( XSPEED_CACHE_DIR, '', (string) $root ), '/' );
	6407	+ $segments = '' === $relative ? array() : explode( '/', $relative );
	6408	+ if ( array_intersect( $segments, array( 'min', 'rest' ) ) ) {
	6409	+ continue;
	6410	+ }
	6411	+ }
	6412	+ if ( ! is_dir( $root ) ) {
	6413	+ continue;
	6414	+ }
	6415	+ $files = glob( $root . '/*.html' );
	6416	+ if ( $files ) {
	6417	+ $count += count( $files );
	6418	+ foreach ( $files as $f ) {
	6419	+ self::sweep_delete( $f );
	6420	+ }
	6421	+ }
	6422	+ // Remove the .meta sidecars (content-type for feeds/sitemaps)
	6423	+ // alongside their .html entries. Not counted — they're not
	6424	+ // cache "pages", just per-entry metadata.
	6425	+ $meta = glob( $root . '/*.meta' );
	6426	+ if ( $meta ) {
	6427	+ foreach ( $meta as $m ) {
	6428	+ self::sweep_delete( $m );
	6429	+ }
	6430	+ }
	6431	+ // Remove precompressed siblings (e.g. <key>.html.br from the Pro
	6432	+ // Brotli module). Not counted — same as .meta. Without this a
	6433	+ // purge leaves stale .br bodies behind: disk bloat, and a
	6434	+ // staleness window if precompression is later disabled.
	6435	+ $br = glob( $root . '/*.br' );
	6436	+ if ( $br ) {
	6437	+ foreach ( $br as $b ) {
	6438	+ self::sweep_delete( $b );
	6439	+ }
	6440	+ }
	6441	+ // `*.br` does not match `*.br.size` — same reason as the flat-root
	6442	+ // sweep above: a size record outliving its body would later be
	6443	+ // read against a different sibling's bytes.
	6444	+ $br_size = glob( $root . '/*.br.size' );
	6445	+ if ( $br_size ) {
	6446	+ foreach ( $br_size as $b ) {
	6447	+ self::sweep_delete( $b );
	6448	+ }
	6449	+ }
	6450	+ }
	6451	+ }
879	6452	// Static-cache tree purge — recursive because the layout is
880	6453	// xspeed-static/{host}/{path}/index.html, so a flat glob can't
881		- // reach everything.
	6454	+ // reach everything. Already host-segmented, so scoping is just a
	6455	+ // matter of starting one level down.
882	6456	if ( is_dir( XSPEED_CACHE_STATIC_DIR ) ) {
883		- $count += self::rmtree_html( XSPEED_CACHE_STATIC_DIR );
	6457	+ $static_root = $network_wide
	6458	+ ? XSPEED_CACHE_STATIC_DIR
	6459	+ : XSPEED_CACHE_STATIC_DIR . '/' . $static_scope;
	6460	+ if ( is_dir( $static_root ) ) {
	6461	+ $count += self::rmtree_html( $static_root );
	6462	+ }
884	6463	}
885	6464	// REST response cache (cache/xspeed/rest/*.json) — same purge
886	6465	// triggers (publish, settings change) invalidate it too.
887		- $count += Rest_Cache::purge();
	6466	+ $rest = Rest_Cache::purge();
	6467	+ $count += $rest;
	6468	+
	6469	+ // Minified + combined CSS/JS (cache/xspeed/min/ and min/combined/)
	6470	+ // go only on a NETWORK-wide sweep.
	6471	+ //
	6472	+ // They are named by content, so a site purge gains nothing by deleting
	6473	+ // them: the next render links the same names for unchanged sources
	6474	+ // and new names for changed ones. Deleting them did cost something.
	6475	+ // A page rendered just before the purge and stored just after linked
	6476	+ // files that were gone (unstyled until the TTL), and min/ is shared
	6477	+ // by every blog, so one subsite's purge broke every other subsite's
	6478	+ // cached pages. Orphans are Cache_GC's job; a network purge, an
	6479	+ // update, the explicit assets purge and deactivation still clear the
	6480	+ // tree, and the purge stamp stops a render in flight from being
	6481	+ // stored against deleted files.
	6482	+ $assets = ( $network_wide && class_exists( '\\XSpeed\\Minifier' ) ) ? Minifier::purge_minified() : 0;
	6483	+
	6484	+ return array(
	6485	+ 'pages' => $count - $rest,
	6486	+ 'rest' => $rest,
	6487	+ 'assets' => $assets,
	6488	+ 'bytes' => self::$sweep_bytes,
	6489	+ );
	6490	+ }
	6491	+
	6492	+ /**
	6493	+ * Flush the persistent object cache (Redis / Memcached).
	6494	+ *
	6495	+ * Runs regardless of whether the Object Cache module is currently
	6496	+ * enabled — a drop-in installed earlier keeps serving until flushed.
	6497	+ *
	6498	+ * @param bool $network_wide Flush every blog's entries. wp_cache_flush()
	6499	+ * is NETWORK-global, so on multisite the
	6500	+ * default prefers the blog-scoped group flush
	6501	+ * (WP 6.1+) — otherwise one site's purge drops
	6502	+ * every other site's object cache, the same bug
	6503	+ * #6 fixed for the page cache.
	6504	+ * @return bool Whether a flush was actually performed.
	6505	+ */
	6506	+ public static function flush_object_cache( bool $network_wide = false ): bool {
	6507	+ if ( ! $network_wide && is_multisite() && function_exists( 'wp_cache_flush_group' ) && function_exists( 'wp_cache_supports' ) && wp_cache_supports( 'flush_group' ) ) {
	6508	+ // Blog-scoped groups only; a shared/global group (site options,
	6509	+ // user meta) is intentionally left alone.
	6510	+ foreach ( array( 'options', 'posts', 'terms', 'post_meta', 'comment' ) as $group ) {
	6511	+ wp_cache_flush_group( $group );
	6512	+ }
	6513	+ return true;
	6514	+ }
	6515	+ if ( function_exists( 'wp_cache_flush' ) ) {
	6516	+ return (bool) wp_cache_flush();
	6517	+ }
	6518	+ return false;
	6519	+ }
	6520	+
	6521	+ /**
	6522	+ * Purge this site's cache: the local sweep, then the object cache, then
	6523	+ * the bookkeeping every caller expects (stats, `xspeed_after_purge_all`,
	6524	+ * inventory invalidation, purge log).
	6525	+ *
	6526	+ * @param string $cause Who asked, for the purge log.
	6527	+ * @param string|null $host See purge_local().
	6528	+ * @param array<string,mixed> $invalidation Public adapter policy. `scope`
	6529	+ * is urls/site/network/none,
	6530	+ * `intent` explains why, and
	6531	+ * `urls` supplies exact targets.
	6532	+ * @return int Page + REST entries removed.
	6533	+ */
	6534	+ public static function purge_all( string $cause = 'manual', ?string $host = null, array $invalidation = array() ) {
	6535	+ $network_wide = ( '*' === $host );
	6536	+ $adapter_scope = isset( $invalidation['scope'] ) && is_string( $invalidation['scope'] )
	6537	+ ? $invalidation['scope']
	6538	+ : ( $network_wide ? 'network' : 'site' );
	6539	+ if ( ! in_array( $adapter_scope, array( 'urls', 'site', 'network', 'none' ), true ) ) {
	6540	+ $adapter_scope = $network_wide ? 'network' : 'site';
	6541	+ }
	6542	+ if ( $network_wide ) {
	6543	+ $adapter_scope = 'network';
	6544	+ }
	6545	+ $intent = isset( $invalidation['intent'] ) && is_string( $invalidation['intent'] ) && '' !== $invalidation['intent']
	6546	+ ? $invalidation['intent']
	6547	+ : 'complete';
	6548	+ $urls = isset( $invalidation['urls'] ) && is_array( $invalidation['urls'] )
	6549	+ ? array_values( array_unique( array_filter( $invalidation['urls'], 'is_string' ) ) )
	6550	+ : array();
	6551	+ // This method always sweeps a complete local bucket. A narrower adapter
	6552	+ // announcement would claim unrelated local pages stayed warm when they
	6553	+ // did not, leaving their server copies stale. Until purge_all() gains
	6554	+ // dependency-aware local deletion, its response scope cannot be `urls`.
	6555	+ if ( 'urls' === $adapter_scope ) {
	6556	+ $adapter_scope = $network_wide ? 'network' : 'site';
	6557	+ }
	6558	+ if ( 'site' === $adapter_scope || 'network' === $adapter_scope || 'none' === $adapter_scope ) {
	6559	+ $urls = array();
	6560	+ }
	6561	+
	6562	+ $fallback = isset( $invalidation['fallback'] ) && is_string( $invalidation['fallback'] ) ? $invalidation['fallback'] : '';
	6563	+
	6564	+ $removed = self::purge_local( $host );
	6565	+ $count = $removed['pages'] + $removed['rest'];
	6566	+
	6567	+ self::flush_object_cache( $network_wide );
	6568	+
888	6569	self::update_stats( array( 'last_purge' => time() ) );
889	6570
	6571	+ // Fire AFTER the local sweep so module listeners (Critical CSS,
	6572	+ // Unused CSS, Cloudflare edge purge) run — this action had three
	6573	+ // registered listeners but was never emitted. Treat it as additive
	6574	+ // (CDN / edge invalidation), not the mechanism for clearing local
	6575	+ // files. (FBS-83114)
	6576	+ // Wrapped: this action predates the purge-event contract and has its
	6577	+ // own third-party listeners. One of them throwing used to abort
	6578	+ // purge_all() here, which now also means the contract event below
	6579	+ // never fires and a server cache keeps serving stale HTML. The local
	6580	+ // sweep is already done by this point, so swallowing is strictly safer
	6581	+ // than letting a listener decide the rest of the method runs.
	6582	+ try {
	6583	+ // Isolated per listener: one throwing used to cancel every
	6584	+ // listener queued behind it — Critical CSS, Unused CSS and the
	6585	+ // Cloudflare edge purge all hang off this hook. (QA #348)
	6586	+ self::do_action_isolated( 'xspeed_after_purge_all', $cause );
	6587	+ } catch ( \Throwable $e ) {
	6588	+ self::log_purge_listener_error( 'xspeed_after_purge_all', $e );
	6589	+ }
	6590	+
	6591	+ /**
	6592	+ * Fires after a full purge, with the same bounded context shape as
	6593	+ * `xspeed_after_purge_url`.
	6594	+ *
	6595	+ * Distinct from `xspeed_after_purge_all` on purpose. That action is
	6596	+ * the long-standing internal signal — it passes a bare `$cause` string
	6597	+ * and Free's own modules use it for local bookkeeping. This one is the
	6598	+ * documented contract for OUTSIDE integrations: same argument shape as
	6599	+ * the per-URL event, so a server-cache or CDN adapter can subscribe to
	6600	+ * both with one handler and branch on a null `url`.
	6601	+ *
	6602	+ * Fires at most once per purge, and not at all when a listener's own
	6603	+ * purge re-enters xSpeed.
	6604	+ *
	6605	+ * @since 1.2.3
	6606	+ *
	6607	+ * @param array $context {
	6608	+ * @type null $url Always null — a full purge has no single URL.
	6609	+ * @type string $host Host swept, or '*' for the entire tree.
	6610	+ * @type null $path Always null.
	6611	+ * @type string $cause Short label for who asked.
	6612	+ * @type int $removed Number of cache files removed.
	6613	+ * @type string $scope Adapter action: urls/site/network/none.
	6614	+ * @type string $intent content/presentation/complete or a caller-defined intent.
	6615	+ * @type string[] $urls Exact targets when scope is urls.
	6616	+ * @type string $fallback Why a change that would have cleared
	6617	+ * only its own pages cleared the whole site
	6618	+ * instead: `theme_list`, `limit`, `pending`
	6619	+ * or `filter`. Empty for every other purge.
	6620	+ * See the purge-event contract in
	6621	+ * docs/guides/hooks-and-filters.md.
	6622	+ * }
	6623	+ */
	6624	+ self::dispatch_purge_event(
	6625	+ 'xspeed_after_purge',
	6626	+ array(
	6627	+ 'url' => null,
	6628	+ 'host' => null === $host ? self::current_purge_host() : (string) $host,
	6629	+ 'path' => null,
	6630	+ 'cause' => $cause,
	6631	+ 'removed' => $count,
	6632	+ 'scope' => $adapter_scope,
	6633	+ 'intent' => $intent,
	6634	+ 'urls' => $urls,
	6635	+ 'fallback' => $fallback,
	6636	+ )
	6637	+ );
	6638	+
	6639	+ /*
	6640	+ * The generic event is published by the `dispatch_purge_event()` call
	6641	+ * directly above, NOT here. Same supersession as in `purge_url()`:
	6642	+ * this branch's raw `do_action` with a `count` payload predates #348's
	6643	+ * contract, and keeping both made a full purge publish twice.
	6644	+ */
	6645	+
	6646	+ // The list behind the "Cached pages" card is memoized for a minute;
	6647	+ // a purge has to drop it or the drill-down shows pages that no
	6648	+ // longer exist.
	6649	+ Cache_Inventory::invalidate();
	6650	+
890	6651	// Trigger of WP_CLI / hook / admin-bar purges all hit the same
891	6652	// path. Record once with the supplied cause so the dashboard
892	6653	// activity feed reads naturally.
893	6654	Activity_Log::record(
		@@ -894,11 +6655,1095 @@
894	6655	'cache_purged',
895	6656	sprintf( 'Cache purged (%s) — %d file%s removed', $cause, $count, 1 === $count ? '' : 's' ),
896	6657	Activity_Log::INFO
897	6658	);
	6659	+
	6660	+ return $count;
898	6661	}
899	6662
900	6663	/**
	6664	+ * Purge everything after a plugin / theme / core update completes.
	6665	+ *
	6666	+ * Bound to `upgrader_process_complete`, which is the only hook an update
	6667	+ * fires — no activation hook runs, so without this the cached HTML (and
	6668	+ * the asset URLs baked into it) outlives the code that produced it.
	6669	+ *
	6670	+ * Runs for plugin, theme and core updates alike, including bulk runs and
	6671	+ * auto-updates, and purges the WHOLE network rather than the current
	6672	+ * site — see the call below. Translation updates are skipped: they
	6673	+ * change no markup a cached page depends on, and language packs update
	6674	+ * often enough that purging on them would keep a multilingual site
	6675	+ * permanently cold.
	6676	+ *
	6677	+ * Note this cannot be folded into the `$invalidate_hooks` loop above:
	6678	+ * that binds `purge_all` directly, and `purge_all( string $cause )` would
	6679	+ * then receive the WP_Upgrader instance as its cause.
	6680	+ *
	6681	+ * @param mixed $upgrader WP_Upgrader instance (unused).
	6682	+ * @param array $hook_extra Context for the completed operation.
	6683	+ * @return void
	6684	+ */
	6685	+ public static function purge_after_upgrade( $upgrader = null, $hook_extra = array() ) {
	6686	+ $cleared = self::$upgrade_cleared_destination;
	6687	+
	6688	+ if ( ! self::upgrade_produced_something( $upgrader ) ) {
	6689	+ return;
	6690	+ }
	6691	+
	6692	+ if ( ! self::upgrade_should_purge( is_array( $hook_extra ) ? $hook_extra : array(), $cleared ) ) {
	6693	+ return;
	6694	+ }
	6695	+
	6696	+ self::purge_for_upgrade();
	6697	+ }
	6698	+
	6699	+ /**
	6700	+ * Whether this request's upgrader removed an existing copy.
	6701	+ *
	6702	+ * @var bool
	6703	+ */
	6704	+ private static $upgrade_cleared_destination = false;
	6705	+
	6706	+ /**
	6707	+ * How many `upgrader_process_complete` dispatches are on the stack.
	6708	+ *
	6709	+ * @var int
	6710	+ */
	6711	+ private static $upgrade_dispatch_depth = 0;
	6712	+
	6713	+ /**
	6714	+ * Enter an `upgrader_process_complete` dispatch.
	6715	+ *
	6716	+ * Bound at PHP_INT_MIN, so it runs before any listener that might read
	6717	+ * the replacement signal. Public because it is a hook target.
	6718	+ *
	6719	+ * @return void
	6720	+ */
	6721	+ public static function note_upgrade_dispatch(): void {
	6722	+ ++self::$upgrade_dispatch_depth;
	6723	+ }
	6724	+
	6725	+ /**
	6726	+ * Drop the replacement signal once every listener has read it.
	6727	+ *
	6728	+ * Bound at PHP_INT_MAX so a second upgrade in the same request starts
	6729	+ * clean, without taking the answer away from the add-on callbacks that
	6730	+ * run at the same priority as ours.
	6731	+ *
	6732	+ * Only the OUTERMOST dispatch clears it. A nested run — core's language
	6733	+ * pack upgrader, or any add-on that installs something from this hook —
	6734	+ * fires the action again, and clearing there would answer for a run that
	6735	+ * has not finished. Called directly (no dispatch on the stack) it still
	6736	+ * clears, which is what a test wants.
	6737	+ *
	6738	+ * Known limit: a nested run INHERITS the outer run's signal, because the
	6739	+ * only evidence we get is a filter that fires before the nested dispatch
	6740	+ * begins and carries no upgrader identity. So a fresh install performed
	6741	+ * from inside a replacement run reads as a replacement and purges once
	6742	+ * more than it needs to. A cold cache is the cheap direction, and the
	6743	+ * alternative — scoping the signal per upgrader — is not knowable from
	6744	+ * `upgrader_clear_destination`.
	6745	+ *
	6746	+ * The observed-destination signal is dropped here too. The two are read
	6747	+ * together and have to expire together: leaving "the directory was not
	6748	+ * there" behind would let a first install answer for whatever ran next
	6749	+ * in the same request, and that one's mistake is a cache left stale.
	6750	+ *
	6751	+ * @return void
	6752	+ */
	6753	+ public static function forget_cleared_destination(): void {
	6754	+ if ( self::$upgrade_dispatch_depth > 0 ) {
	6755	+ --self::$upgrade_dispatch_depth;
	6756	+ }
	6757	+
	6758	+ if ( 0 === self::$upgrade_dispatch_depth ) {
	6759	+ self::$upgrade_cleared_destination = false;
	6760	+ self::$upgrade_destination_existed = null;
	6761	+ self::$upgrade_destination_folder = '';
	6762	+ }
	6763	+ }
	6764	+
	6765	+ /**
	6766	+ * Whether the destination this run installs into was already there.
	6767	+ *
	6768	+ * Null while unknown — an upgrader whose target we cannot work out keeps
	6769	+ * the old behaviour rather than being guessed at.
	6770	+ *
	6771	+ * @var bool|null
	6772	+ */
	6773	+ private static $upgrade_destination_existed = null;
	6774	+
	6775	+ /**
	6776	+ * The folder name that answer was measured against, so the destination
	6777	+ * WordPress reports on `upgrader_clear_destination` can be checked
	6778	+ * against it. Empty when nothing was measured.
	6779	+ *
	6780	+ * @var string
	6781	+ */
	6782	+ private static $upgrade_destination_folder = '';
	6783	+
	6784	+ /**
	6785	+ * Note whether the package's destination exists, before it is cleared.
	6786	+ *
	6787	+ * `upgrader_source_selection` is the last hook that fires while the old
	6788	+ * copy is still on disk, and the extracted source folder name is the
	6789	+ * directory the package will install into. A pass-through listener: the
	6790	+ * source is returned untouched.
	6791	+ *
	6792	+ * @param mixed $source Extracted package directory.
	6793	+ * @param mixed $remote_src Unused; the package's remote source.
	6794	+ * @param mixed $upgrader The upgrader instance, if one was supplied.
	6795	+ * @param mixed $hook_extra Context supplied by the upgrader.
	6796	+ * @return mixed The source, unchanged.
	6797	+ */
	6798	+ public static function note_destination_state( $source, $remote_src = '', $upgrader = null, $hook_extra = array() ) {
	6799	+ self::$upgrade_destination_existed = null;
	6800	+ self::$upgrade_destination_folder = '';
	6801	+
	6802	+ $root = self::upgrade_destination_root( $upgrader, is_array( $hook_extra ) ? $hook_extra : array() );
	6803	+ if ( null !== $root && is_string( $source ) && '' !== $source ) {
	6804	+ $folder = basename( rtrim( $source, '/\\' ) );
	6805	+ if ( '' !== $folder ) {
	6806	+ self::$upgrade_destination_existed = is_dir( rtrim( $root, '/\\' ) . '/' . $folder );
	6807	+ self::$upgrade_destination_folder = $folder;
	6808	+ }
	6809	+ }
	6810	+
	6811	+ return $source;
	6812	+ }
	6813	+
	6814	+ /**
	6815	+ * Where a package of this kind installs to, or null if we cannot tell.
	6816	+ *
	6817	+ * @param mixed $upgrader The upgrader instance, if one was supplied.
	6818	+ * @param array $hook_extra Context supplied by the upgrader.
	6819	+ * @return string|null
	6820	+ */
	6821	+ private static function upgrade_destination_root( $upgrader, array $hook_extra ): ?string {
	6822	+ $type = isset( $hook_extra['type'] ) ? (string) $hook_extra['type'] : '';
	6823	+
	6824	+ if ( 'plugin' === $type || $upgrader instanceof \Plugin_Upgrader ) {
	6825	+ return defined( 'WP_PLUGIN_DIR' ) ? WP_PLUGIN_DIR : null;
	6826	+ }
	6827	+
	6828	+ if ( 'theme' === $type || $upgrader instanceof \Theme_Upgrader ) {
	6829	+ return function_exists( 'get_theme_root' ) ? (string) get_theme_root() : null;
	6830	+ }
	6831	+
	6832	+ return null;
	6833	+ }
	6834	+
	6835	+ /**
	6836	+ * Record that the upgrader cleared an existing destination.
	6837	+ *
	6838	+ * A pass-through listener on `upgrader_clear_destination`: WordPress only
	6839	+ * fires it when `clear_destination` was set AND something was there to
	6840	+ * remove, which is the one signal that separates an upload-and-replace
	6841	+ * from a first-time install. The filtered value is returned untouched.
	6842	+ *
	6843	+ * @param true|\WP_Error $removed Whether the destination was cleared.
	6844	+ * @return true|\WP_Error
	6845	+ */
	6846	+ public static function note_cleared_destination( $removed, $local_destination = '', $remote_destination = '', $hook_extra = array() ) {
	6847	+ if ( ! is_wp_error( $removed ) ) {
	6848	+ self::$upgrade_cleared_destination = true;
	6849	+ }
	6850	+
	6851	+ // $remote_destination is the directory WordPress actually cleared,
	6852	+ // derived from the source AFTER every `upgrader_source_selection`
	6853	+ // listener ran. If its folder is not the one note_destination_state()
	6854	+ // measured, a listener that ran after ours renamed the package, and
	6855	+ // the "was it there?" answer is about a directory that was never going
	6856	+ // to be written. Unknown is the answer that purges, so that is what it
	6857	+ // becomes. Only the last segment is compared: over FTP the remote
	6858	+ // path sits under the server's own root, not WP_PLUGIN_DIR. (#407 QA)
	6859	+ if ( is_string( $remote_destination ) && '' !== $remote_destination ) {
	6860	+ $cleared_folder = basename( rtrim( $remote_destination, '/\\' ) );
	6861	+ if ( '' !== $cleared_folder && $cleared_folder !== self::$upgrade_destination_folder ) {
	6862	+ self::$upgrade_destination_existed = null;
	6863	+ }
	6864	+ }
	6865	+
	6866	+ return $removed;
	6867	+ }
	6868	+
	6869	+ /**
	6870	+ * Did the completed run actually replace anything?
	6871	+ *
	6872	+ * `upgrader_process_complete` fires whether the run succeeded or failed —
	6873	+ * the failure branch in WP_Upgrader::run() only feeds the skin before the
	6874	+ * action fires. A run that installed nothing changed no markup, so purging
	6875	+ * for it is a cold cache bought for nothing.
	6876	+ *
	6877	+ * Deliberately conservative: this returns false ONLY when every result we
	6878	+ * can see is an error. An upgrader we cannot read, a mixed bulk run, or a
	6879	+ * missing result all fall through to purging, which is the safe direction
	6880	+ * everywhere else in this handler.
	6881	+ *
	6882	+ * @param mixed $upgrader WP_Upgrader instance, or anything else.
	6883	+ * @return bool
	6884	+ */
	6885	+ public static function upgrade_produced_something( $upgrader ): bool {
	6886	+ if ( ! is_object( $upgrader ) ) {
	6887	+ return true;
	6888	+ }
	6889	+
	6890	+ // A bulk run collects one entry per item; `result` alone would only
	6891	+ // describe the last of them.
	6892	+ if ( isset( $upgrader->results ) && is_array( $upgrader->results ) && ! empty( $upgrader->results ) ) {
	6893	+ foreach ( $upgrader->results as $result ) {
	6894	+ if ( ! is_wp_error( $result ) && ! empty( $result ) ) {
	6895	+ return true;
	6896	+ }
	6897	+ }
	6898	+ return false;
	6899	+ }
	6900	+
	6901	+ if ( ! property_exists( $upgrader, 'result' ) ) {
	6902	+ return true;
	6903	+ }
	6904	+
	6905	+ return ! is_wp_error( $upgrader->result ) && ! empty( $upgrader->result );
	6906	+ }
	6907	+
	6908	+ /**
	6909	+ * Decide whether a completed operation invalidates the cache.
	6910	+ *
	6911	+ * Split out from the handler so the decision is testable on its own:
	6912	+ * purge_all() reaches straight for glob() and unlink(), which a unit test
	6913	+ * cannot observe honestly, while every rule that matters lives here.
	6914	+ *
	6915	+ * @param array $hook_extra Context for the completed operation.
	6916	+ * @return bool
	6917	+ */
	6918	+ public static function upgrade_should_purge( array $hook_extra, bool $destination_cleared = false ): bool {
	6919	+ if ( ! self::upgrade_replaced_code( $hook_extra, $destination_cleared ) ) {
	6920	+ return false;
	6921	+ }
	6922	+
	6923	+ // An update to xSpeed ITSELF always purges, whatever the setting says.
	6924	+ // This plugin's own code is what rendered every cached page — the
	6925	+ // minifier, lazy-loader, resource hints and CDN rewriter all changed
	6926	+ // underneath it — so serving that HTML after an update means serving
	6927	+ // output from a version that no longer exists. Minified assets make it
	6928	+ // concrete rather than theoretical: their filenames are keyed on the
	6929	+ // source filemtime, so they regenerate under NEW hashes while the
	6930	+ // cached pages still link the old ones, and the page requests files
	6931	+ // that are no longer on disk. Offering an opt-out for that would be
	6932	+ // offering a broken site.
	6933	+ return self::upgrade_touches_xspeed( $hook_extra ) || self::purge_on_upgrade_enabled();
	6934	+ }
	6935	+
	6936	+ /**
	6937	+ * Did this completed run replace code that renders pages?
	6938	+ *
	6939	+ * The half of the decision that has nothing to do with our settings: it
	6940	+ * asks only whether live code changed underneath the output we cached.
	6941	+ * Add-ons that keep their own derived artifacts — generated CSS, captured
	6942	+ * selectors, fingerprints — need the same answer and must not have to
	6943	+ * rebuild these rules, or they drift apart. Call it with the hook's own
	6944	+ * `$hook_extra`; the upload-and-replace signal is read from this request.
	6945	+ *
	6946	+ * Deliberately independent of the "Purge After Updates" setting. That
	6947	+ * setting governs the page cache, not whether an add-on's derived data is
	6948	+ * still valid.
	6949	+ *
	6950	+ * @param array $hook_extra Context for the completed operation.
	6951	+ * @param bool|null $destination_cleared Override the recorded signal; null reads this request's.
	6952	+ * @return bool
	6953	+ */
	6954	+ public static function upgrade_replaced_code( array $hook_extra, ?bool $destination_cleared = null ): bool {
	6955	+ $cleared = null === $destination_cleared ? self::$upgrade_cleared_destination : $destination_cleared;
	6956	+
	6957	+ $type = isset( $hook_extra['type'] ) ? (string) $hook_extra['type'] : '';
	6958	+ $action = isset( $hook_extra['action'] ) ? (string) $hook_extra['action'] : '';
	6959	+
	6960	+ // `upgrader_process_complete` fires for INSTALLS as well as updates.
	6961	+ // A freshly installed plugin is inactive and a freshly installed theme
	6962	+ // is not the active one, so neither can change a single rendered page
	6963	+ // — but the first cut of this handler purged the whole tree anyway, so
	6964	+ // evaluating three plugins in a row emptied the cache three times.
	6965	+ //
	6966	+ // 'install' alone is NOT enough to skip on, because WordPress reports
	6967	+ // an upload-and-replace as an install: `Plugin_Upgrader::install()`
	6968	+ // hardcodes `action => install` and `overwrite_package` does not change
	6969	+ // it, so "Replace current with uploaded" and `wp plugin install <zip>
	6970	+ // --force` both arrive here labelled install while genuinely replacing
	6971	+ // live code. That is how a plugin distributed as a zip is updated, and
	6972	+ // skipping it put back the stale markup this handler exists to clear.
	6973	+ //
	6974	+ // The distinguishing signal is whether the destination was cleared:
	6975	+ // WP_Upgrader only fires `upgrader_clear_destination` when it removed
	6976	+ // something that was already there. Installing beside nothing does not.
	6977	+ if ( 'install' === $action && ! $cleared ) {
	6978	+ return false;
	6979	+ }
	6980	+
	6981	+ // A cleared destination is only evidence of a replacement if there was
	6982	+ // something in it. Core returns success from clear_destination() for a
	6983	+ // destination that never existed, so a first-time install arrived here
	6984	+ // looking exactly like an upload-and-replace and bought a cold cache
	6985	+ // for a plugin that is not even active yet. Only acted on when we
	6986	+ // positively know the directory was absent.
	6987	+ if ( 'install' === $action && false === self::$upgrade_destination_existed ) {
	6988	+ return false;
	6989	+ }
	6990	+
	6991	+ // 'translation' is the one update type that cannot change rendered
	6992	+ // markup. Anything else — including an empty type from a custom
	6993	+ // updater — is treated as cache-invalidating, because guessing wrong
	6994	+ // in that direction only costs a cold cache.
	6995	+ if ( 'translation' === $type ) {
	6996	+ return false;
	6997	+ }
	6998	+
	6999	+ return true;
	7000	+ }
	7001	+
	7002	+ /**
	7003	+ * Purge everything an update can invalidate.
	7004	+ *
	7005	+ * Network-wide ('*'), not the calling site's bucket. A plugin, theme or
	7006	+ * core update replaces code shared by EVERY site on the network, so a
	7007	+ * scoped purge would clear the site that happened to run the updater and
	7008	+ * leave every other subsite serving pre-update HTML for the whole TTL —
	7009	+ * the very bug this handler exists to fix, one level down. On single-site
	7010	+ * this is identical to the scoped call, since there is only ever one
	7011	+ * bucket.
	7012	+ *
	7013	+ * @return void
	7014	+ */
	7015	+ private static function purge_for_upgrade(): void {
	7016	+ // Network-wide, so purge_local() also clears min/.
	7017	+ self::purge_all( 'upgrade', '*' );
	7018	+ }
	7019	+
	7020	+ /**
	7021	+ * Purge after an unattended background update run.
	7022	+ *
	7023	+ * `automatic_updates_complete` passes ONE argument, and it is not a
	7024	+ * hook_extra: it is WordPress's results array, keyed by what was updated
	7025	+ * ('core', 'plugin', 'theme', 'translation'). Handing it to
	7026	+ * purge_after_upgrade() put it in the unused $upgrader slot and left the
	7027	+ * type empty, so a night on which only a language pack updated purged
	7028	+ * every cached page — the exact case the translation exemption exists to
	7029	+ * prevent, and WordPress auto-updates language packs by default.
	7030	+ *
	7031	+ * @param array $results Update results, keyed by type.
	7032	+ * @return void
	7033	+ */
	7034	+ public static function purge_after_auto_updates( $results = array() ): void {
	7035	+ if ( ! self::auto_updates_should_purge( is_array( $results ) ? $results : array() ) ) {
	7036	+ return;
	7037	+ }
	7038	+
	7039	+ self::purge_for_upgrade();
	7040	+ }
	7041	+
	7042	+ /**
	7043	+ * Decide whether a background update run invalidates the cache.
	7044	+ *
	7045	+ * @param array $results Update results, keyed by type.
	7046	+ * @return bool
	7047	+ */
	7048	+ public static function auto_updates_should_purge( array $results ): bool {
	7049	+ // An unrecognisable payload is treated as invalidating, the same
	7050	+ // direction every other unknown takes here.
	7051	+ if ( empty( $results ) ) {
	7052	+ return true;
	7053	+ }
	7054	+
	7055	+ // Failed items are listed alongside successful ones — WP_Automatic_Updater
	7056	+ // appends an entry whatever the outcome — and a night on which every
	7057	+ // update failed replaced no code, so it invalidates nothing.
	7058	+ $updated = array();
	7059	+ foreach ( $results as $type => $items ) {
	7060	+ if ( ! is_array( $items ) ) {
	7061	+ continue;
	7062	+ }
	7063	+ foreach ( $items as $item ) {
	7064	+ $result = is_object( $item ) && isset( $item->result ) ? $item->result : true;
	7065	+ if ( ! is_wp_error( $result ) && ! empty( $result ) ) {
	7066	+ $updated[] = (string) $type;
	7067	+ break;
	7068	+ }
	7069	+ }
	7070	+ }
	7071	+
	7072	+ if ( empty( $updated ) ) {
	7073	+ return false;
	7074	+ }
	7075	+
	7076	+ // Nothing but language packs: a language pack changes no markup a
	7077	+ // cached page depends on, and purging on one would keep a multilingual
	7078	+ // site permanently cold.
	7079	+ if ( array( 'translation' ) === array_values( array_unique( $updated ) ) ) {
	7080	+ return false;
	7081	+ }
	7082	+
	7083	+ return self::auto_updates_touch_xspeed( $results ) || self::purge_on_upgrade_enabled();
	7084	+ }
	7085	+
	7086	+ /**
	7087	+ * Does a background run include one of our own plugins?
	7088	+ *
	7089	+ * Same rule as a foreground self-update, read out of the results array's
	7090	+ * shape instead of a hook_extra: each plugin entry carries the update
	7091	+ * object on `->item->plugin`.
	7092	+ *
	7093	+ * @param array $results Update results, keyed by type.
	7094	+ * @return bool
	7095	+ */
	7096	+ private static function auto_updates_touch_xspeed( array $results ): bool {
	7097	+ if ( empty( $results['plugin'] ) || ! is_array( $results['plugin'] ) ) {
	7098	+ return false;
	7099	+ }
	7100	+
	7101	+ $ours = self::self_update_plugins();
	7102	+ foreach ( $results['plugin'] as $entry ) {
	7103	+ $item = is_object( $entry ) && isset( $entry->item ) ? $entry->item : null;
	7104	+ $file = is_object( $item ) && isset( $item->plugin ) ? (string) $item->plugin : '';
	7105	+ if ( '' !== $file && in_array( $file, $ours, true ) ) {
	7106	+ return true;
	7107	+ }
	7108	+ }
	7109	+
	7110	+ return false;
	7111	+ }
	7112	+
	7113	+ /**
	7114	+ * Is the "Purge After Updates" setting on?
	7115	+ *
	7116	+ * Gates THIRD-PARTY updates only — an xSpeed self-update ignores it, see
	7117	+ * purge_after_upgrade(). Defaults to true when the option has never been
	7118	+ * written, matching the schema default in CacheModule: an unset value on
	7119	+ * an existing install must not read as "the user turned this off".
	7120	+ *
	7121	+ * Unlike LiteSpeed, which ships the equivalent toggle OFF, this defaults
	7122	+ * ON — a cold cache costs one slow request, whereas stale HTML is a wrong
	7123	+ * page for up to the full TTL and the site owner has no way to tell why.
	7124	+ *
	7125	+ * @return bool
	7126	+ */
	7127	+ private static function purge_on_upgrade_enabled(): bool {
	7128	+ $opts = Settings_Manager::get( 'cache' );
	7129	+ return ! array_key_exists( 'purge_on_upgrade', $opts ) || ! empty( $opts['purge_on_upgrade'] );
	7130	+ }
	7131	+
	7132	+ /**
	7133	+ * Does this completed update include xSpeed itself?
	7134	+ *
	7135	+ * Mirrors the payload shapes Plugin::maybe_restore_after_update() reads:
	7136	+ * a single update carries 'plugin', a bulk run carries 'plugins'.
	7137	+ *
	7138	+ * @param array $hook_extra Context for the completed operation.
	7139	+ * @return bool
	7140	+ */
	7141	+ private static function upgrade_touches_xspeed( array $hook_extra ): bool {
	7142	+ if ( ! isset( $hook_extra['type'] ) || 'plugin' !== $hook_extra['type'] ) {
	7143	+ return false;
	7144	+ }
	7145	+
	7146	+ $updated = array();
	7147	+ if ( isset( $hook_extra['plugins'] ) && is_array( $hook_extra['plugins'] ) ) {
	7148	+ // Strings only: array_intersect() stringifies what it is given, so
	7149	+ // an object without __toString in a custom updater's payload would
	7150	+ // be a fatal rather than a miss.
	7151	+ $updated = array_filter( $hook_extra['plugins'], 'is_string' );
	7152	+ } elseif ( isset( $hook_extra['plugin'] ) && is_string( $hook_extra['plugin'] ) ) {
	7153	+ $updated = array( $hook_extra['plugin'] );
	7154	+ }
	7155	+
	7156	+ return (bool) array_intersect( self::self_update_plugins(), $updated );
	7157	+ }
	7158	+
	7159	+ /**
	7160	+ * Plugin files whose update counts as an update to us.
	7161	+ *
	7162	+ * The self-update rule is "our own code rendered this cached HTML, so it
	7163	+ * must not survive the code being replaced". That is true of any add-on
	7164	+ * that writes into the same page: an add-on inlines critical CSS, rewrites
	7165	+ * stylesheet links and image URLs, and produces the compressed and static
	7166	+ * copies, so its update leaves exactly the stale markup this rule exists
	7167	+ * to clear. Free cannot name an add-on, so it asks instead.
	7168	+ *
	7169	+ * Filter: xspeed_self_update_plugins
	7170	+ *
	7171	+ * Add-ons add their own `plugin_basename( __FILE__ )`. Entries are matched
	7172	+ * against the plugin files WordPress reports for the completed update, so
	7173	+ * a value that is not a `dir/file.php` basename simply never matches.
	7174	+ *
	7175	+ * @param string[] $plugins Plugin basenames treated as our own.
	7176	+ * @return string[]
	7177	+ */
	7178	+ private static function self_update_plugins(): array {
	7179	+ $ours = array( plugin_basename( XSPEED_FILE ) );
	7180	+
	7181	+ /** This filter is documented above. */
	7182	+ $filtered = apply_filters( 'xspeed_self_update_plugins', $ours );
	7183	+
	7184	+ // Our own file is merged back afterwards rather than trusted to survive
	7185	+ // the round trip. A listener that returns null, a bare string, or a
	7186	+ // list it built from scratch would otherwise drop it, and the plugin
	7187	+ // would quietly stop exempting its OWN update from the setting — a
	7188	+ // failure no add-on author would think to test for.
	7189	+ $claimed = array_filter( is_array( $filtered ) ? $filtered : array(), 'is_string' );
	7190	+
	7191	+ return array_values( array_unique( array_merge( $ours, array_filter( $claimed ) ) ) );
	7192	+ }
	7193	+
	7194	+ /**
	7195	+ * Invalidate caches of RENDERED output owned by other plugins.
	7196	+ *
	7197	+ * purge_all() sweeps only what xSpeed wrote. A page builder that stores
	7198	+ * rendered HTML or generated CSS of its own — Elementor's element cache
	7199	+ * and `uploads/elementor/css/`, and the equivalents in Beaver / Divi /
	7200	+ * Bricks / Oxygen — keeps whatever asset URLs were current when it was
	7201	+ * written, and no xSpeed purge has ever reached it.
	7202	+ *
	7203	+ * That only matters for rewrites that happen DURING render rather than on
	7204	+ * the finished page. Minify, combine, lazy-load and resource hints all run
	7205	+ * on `xspeed_cache_final_html` or a `template_redirect` buffer — after the
	7206	+ * builder has already stored its copy — so nothing they emit can leak.
	7207	+ * The CDN module's `wp_get_attachment_url` filter is the one that can.
	7208	+ *
	7209	+ * Called ONLY from purges where asset URLs themselves can have changed
	7210	+ * (a CDN settings write, an explicit Purge All). NOT from purge_all(),
	7211	+ * which also runs on every post publish — regenerating every builder CSS
	7212	+ * file that often would cost more than it saves, and the builder already
	7213	+ * invalidates its own copy for the post being saved.
	7214	+ *
	7215	+ * @param string $cause Who asked. Threaded through to the listeners and
	7216	+ * the activity log.
	7217	+ * @return string[] Labels of the caches that were actually cleared.
	7218	+ */
	7219	+ public static function purge_render_caches( string $cause = 'manual' ): array {
	7220	+ /**
	7221	+ * Clear render caches belonging to other plugins.
	7222	+ *
	7223	+ * A listener does its own work and appends a human-readable label for
	7224	+ * what it cleared, so the activity log can name it. Returning
	7225	+ * `$cleared` unchanged means "nothing of mine is installed" and is the
	7226	+ * correct no-op — never a failure.
	7227	+ *
	7228	+ * Detect the owning plugin by class or constant, not by an
	7229	+ * `is_plugin_active()` path check: a renamed plugin folder must not
	7230	+ * silently disable the integration.
	7231	+ *
	7232	+ * @param string[] $cleared Labels of caches cleared so far.
	7233	+ * @param string $cause Why the purge is happening.
	7234	+ */
	7235	+ $cleared = (array) apply_filters( 'xspeed_purge_third_party_render_caches', array(), $cause );
	7236	+
	7237	+ // Labels are strings destined for the activity feed. Anything else a
	7238	+ // third-party listener returns is dropped rather than coerced — a
	7239	+ // stray `0` or `null` in the log reads as a cache we cleared.
	7240	+ $cleared = array_values(
	7241	+ array_filter(
	7242	+ $cleared,
	7243	+ static function ( $label ) {
	7244	+ return is_string( $label ) && '' !== trim( $label );
	7245	+ }
	7246	+ )
	7247	+ );
	7248	+
	7249	+ if ( ! $cleared ) {
	7250	+ return $cleared;
	7251	+ }
	7252	+
	7253	+ // Logged separately from the page-cache purge above it. "I turned the
	7254	+ // CDN off and the images are still wrong" is only diagnosable if the
	7255	+ // feed says which OTHER plugin's cache was regenerated and when.
	7256	+ Activity_Log::record(
	7257	+ 'cache_purged',
	7258	+ sprintf( 'Render caches cleared (%s) — %s', $cause, implode( ', ', $cleared ) ),
	7259	+ Activity_Log::INFO
	7260	+ );
	7261	+
	7262	+ return $cleared;
	7263	+ }
	7264	+
	7265	+ /**
	7266	+ * The per-type purge menu, LiteSpeed-style. Each entry is a cache type
	7267	+ * the user can purge individually from the admin-bar dropdown. `visible`
	7268	+ * controls whether the item shows (active + licensed module only) — it
	7269	+ * NEVER limits Purge All, which always sweeps everything on disk.
	7270	+ *
	7271	+ * Pro registers its own types (Critical CSS, Unused CSS, …) by filtering
	7272	+ * `xspeed_purge_types`, so Free degrades gracefully when Pro is absent.
	7273	+ *
	7274	+ * @return array<string,array{label:string,visible:bool}>
	7275	+ */
	7276	+ public static function purge_types(): array {
	7277	+ $minify_on = false;
	7278	+ if ( class_exists( '\\XSpeed\\Settings_Manager' ) ) {
	7279	+ $min = Settings_Manager::get( 'minify' );
	7280	+ $minify_on = ! empty( $min['minify_css'] ) || ! empty( $min['minify_js'] ) || ! empty( $min['combine_css'] ) || ! empty( $min['combine_js'] );
	7281	+ }
	7282	+ // Object cache is "active" when an external object-cache drop-in is in
	7283	+ // use — the canonical WP signal, independent of our settings option.
	7284	+ $oc_on = function_exists( 'wp_using_ext_object_cache' ) && wp_using_ext_object_cache();
	7285	+
	7286	+ $types = array(
	7287	+ 'all' => array(
	7288	+ 'label' => __( 'Purge All', 'xspeed' ),
	7289	+ 'visible' => true,
	7290	+ ),
	7291	+ 'page' => array(
	7292	+ 'label' => __( 'Purge Page / Static Cache', 'xspeed' ),
	7293	+ 'visible' => true,
	7294	+ ),
	7295	+ 'assets' => array(
	7296	+ 'label' => __( 'Purge CSS / JS Cache', 'xspeed' ),
	7297	+ 'visible' => $minify_on,
	7298	+ ),
	7299	+ 'object' => array(
	7300	+ 'label' => __( 'Purge Object Cache', 'xspeed' ),
	7301	+ 'visible' => $oc_on,
	7302	+ ),
	7303	+ 'rest' => array(
	7304	+ 'label' => __( 'Purge REST Cache', 'xspeed' ),
	7305	+ 'visible' => true,
	7306	+ ),
	7307	+ );
	7308	+
	7309	+ /**
	7310	+ * Filter the admin-bar purge-type menu. Pro modules add their own
	7311	+ * (Critical CSS, Unused CSS, CDN). Adding a type here only adds a
	7312	+ * MENU item — purge_type() must know how to handle the same slug.
	7313	+ *
	7314	+ * @param array $types Map of slug => [label, visible].
	7315	+ */
	7316	+ return (array) apply_filters( 'xspeed_purge_types', $types );
	7317	+ }
	7318	+
	7319	+ /**
	7320	+ * Purge a single cache type by slug. 'all' delegates to purge_all();
	7321	+ * every other slug clears just its own artifacts. Unknown slugs (e.g. a
	7322	+ * Pro type) fan out via the `xspeed_purge_type_{slug}` action so the
	7323	+ * owning module can handle it. Returns the number of items removed where
	7324	+ * countable.
	7325	+ *
	7326	+ * @param string $type Cache type slug.
	7327	+ * @param string $cause Who asked. Threaded through so the purge log can
	7328	+ * tell an AI assistant's purge apart from a click —
	7329	+ * "the cache cleared four times today" is only
	7330	+ * actionable once you know what kept clearing it.
	7331	+ */
	7332	+ public static function purge_type( string $type, string $cause = 'manual' ): int {
	7333	+ switch ( $type ) {
	7334	+ case 'all':
	7335	+ $count = self::purge_all( $cause );
	7336	+ // "Purge All" is the user saying they don't trust anything
	7337	+ // stored anywhere — the one purge that should also reach
	7338	+ // caches of rendered output we don't own. purge_all() itself
	7339	+ // deliberately does NOT, because it also runs on every post
	7340	+ // publish. (See Render_Caches.)
	7341	+ self::purge_render_caches( $cause );
	7342	+ return $count;
	7343	+
	7344	+ case 'page':
	7345	+ $count = self::purge_pages();
	7346	+ self::update_stats( array( 'last_purge' => time() ) );
	7347	+ Cache_Inventory::invalidate();
	7348	+ self::record_partial_purge( 'page', $cause, $count );
	7349	+ self::announce_purge( $cause, $count );
	7350	+ return $count;
	7351	+
	7352	+ case 'assets':
	7353	+ return self::purge_assets( $cause );
	7354	+
	7355	+ case 'object':
	7356	+ if ( function_exists( 'wp_cache_flush' ) ) {
	7357	+ wp_cache_flush();
	7358	+ }
	7359	+ self::record_partial_purge( 'object cache', $cause, null );
	7360	+ return 0;
	7361	+
	7362	+ case 'rest':
	7363	+ $count = Rest_Cache::purge();
	7364	+ self::record_partial_purge( 'REST responses', $cause, $count );
	7365	+ self::announce_purge( $cause, $count );
	7366	+ return $count;
	7367	+
	7368	+ default:
	7369	+ return self::purge_type_unhandled( $type, $cause );
	7370	+ }
	7371	+ }
	7372	+
	7373	+ /**
	7374	+ * Whether a widget change already purged in this request.
	7375	+ *
	7376	+ * @var bool
	7377	+ */
	7378	+ private static $widgets_purged = false;
	7379	+
	7380	+ /**
	7381	+ * A widget option changed: purge when it is a widget's settings.
	7382	+ *
	7383	+ * @param string $option Option name.
	7384	+ */
	7385	+ public static function on_widget_option_change( $option ): void {
	7386	+ if ( is_string( $option ) && 0 === strpos( $option, 'widget_' ) ) {
	7387	+ self::on_widgets_change();
	7388	+ }
	7389	+ }
	7390	+
	7391	+ /**
	7392	+ * A widget was added, removed, moved or edited. Sidebars render on every
	7393	+ * page, so the whole site goes, once per request: one save writes both
	7394	+ * `sidebars_widgets` and the widget's own option.
	7395	+ *
	7396	+ * A Customizer publish writes the same options and purges on its own
	7397	+ * (on_customize_save()), so it is left to that.
	7398	+ */
	7399	+ public static function on_widgets_change(): void {
	7400	+ if ( self::$widgets_purged || did_action( 'customize_save' ) ) {
	7401	+ return;
	7402	+ }
	7403	+ self::$widgets_purged = true;
	7404	+ self::purge_all(
	7405	+ 'widgets',
	7406	+ null,
	7407	+ array(
	7408	+ 'scope' => 'site',
	7409	+ 'intent' => 'presentation',
	7410	+ 'urls' => array(),
	7411	+ )
	7412	+ );
	7413	+ }
	7414	+
	7415	+ /**
	7416	+ * Purge this site's pages after a Customizer publish.
	7417	+ *
	7418	+ * A presentation change: every page's markup or inline CSS may differ, so
	7419	+ * the whole site bucket goes, as for a template or global-styles edit.
	7420	+ * min/ stays, because its files are named by content; this blog's
	7421	+ * manifests are dropped so the next render re-reads every source rather
	7422	+ * than trusting a signature. Bound with no arguments, because the hook
	7423	+ * passes the WP_Customize_Manager, which purge_all() would take as its
	7424	+ * cause.
	7425	+ */
	7426	+ public static function on_customize_save(): void {
	7427	+ self::purge_all(
	7428	+ 'customizer',
	7429	+ null,
	7430	+ array(
	7431	+ 'scope' => 'site',
	7432	+ 'intent' => 'presentation',
	7433	+ 'urls' => array(),
	7434	+ )
	7435	+ );
	7436	+ if ( class_exists( '\\XSpeed\\Minifier' ) ) {
	7437	+ Minifier::purge_manifests( Asset_Manifest::blog_id() );
	7438	+ }
	7439	+ }
	7440	+
	7441	+ /**
	7442	+ * Purge minified and combined CSS/JS, and the pages that link them.
	7443	+ *
	7444	+ * Scope follows who shares what:
	7445	+ *
	7446	+ * - Single site: min/ is deleted outright.
	7447	+ * - One site of a network: min/ is shared by every blog, so only this
	7448	+ * blog's manifests go. Its next render re-reads each source and
	7449	+ * rebuilds only what changed; no other blog loses a file it links.
	7450	+ * Outputs nothing links any more are left to Cache_GC.
	7451	+ * - $network: min/ and every blog's pages, network-wide.
	7452	+ *
	7453	+ * Deleting min/ without clearing the pages that link it left every
	7454	+ * cached page pointing at files that no longer exist. WordPress answers
	7455	+ * the missing asset by 301-ing to its pretty-permalink form and serving
	7456	+ * the 404 TEMPLATE as `HTTP 200 text/html`, which the browser accepts as
	7457	+ * a stylesheet and parses to zero rules — no console error, no network
	7458	+ * failure, no 4xx anywhere in devtools. The pages stayed broken for the
	7459	+ * rest of the TTL, and the admin who clicked could not see it: they are
	7460	+ * logged in, so their own requests bypass the page cache. (#244) So the
	7461	+ * pages go too, and when files were actually deleted the edge is told
	7462	+ * through `xspeed_after_purge_all`, or it keeps serving HTML that links
	7463	+ * them.
	7464	+ *
	7465	+ * The public `xspeed_after_purge` event carries intent `assets`: rendered
	7466	+ * markup did not change, only asset files did. A listener that keeps
	7467	+ * measurements of rendered pages (selectors, layout) can keep them.
	7468	+ *
	7469	+ * @param string $cause Who asked.
	7470	+ * @param bool $network Purge every blog's pages and all of min/.
	7471	+ * @return int Page entries removed.
	7472	+ */
	7473	+ public static function purge_assets( string $cause, bool $network = false ): int {
	7474	+ $deleted = 0;
	7475	+ $rest = 0;
	7476	+ if ( $network ) {
	7477	+ // purge_local('*') clears min/ itself on a network-wide sweep.
	7478	+ $removed = self::purge_local( '*' );
	7479	+ $count = (int) $removed['pages'];
	7480	+ $rest = (int) $removed['rest'];
	7481	+ $deleted = (int) $removed['assets'];
	7482	+ } else {
	7483	+ if ( class_exists( '\\XSpeed\\Minifier' ) && is_multisite() ) {
	7484	+ Minifier::purge_manifests( Asset_Manifest::blog_id() );
	7485	+ } elseif ( class_exists( '\\XSpeed\\Minifier' ) ) {
	7486	+ $deleted = Minifier::purge_minified();
	7487	+ }
	7488	+ $count = self::purge_pages();
	7489	+ }
	7490	+
	7491	+ self::update_stats( array( 'last_purge' => time() ) );
	7492	+ Cache_Inventory::invalidate();
	7493	+ self::record_partial_purge( 'assets', $cause, $count + $rest );
	7494	+
	7495	+ if ( $deleted > 0 || $network ) {
	7496	+ try {
	7497	+ self::do_action_isolated( 'xspeed_after_purge_all', $cause );
	7498	+ } catch ( \Throwable $e ) {
	7499	+ self::log_purge_listener_error( 'xspeed_after_purge_all', $e );
	7500	+ }
	7501	+ }
	7502	+
	7503	+ if ( ! $network ) {
	7504	+ self::announce_purge( $cause, $count, 'site', 'assets' );
	7505	+ } elseif ( function_exists( 'do_action' ) ) {
	7506	+ try {
	7507	+ self::dispatch_purge_event(
	7508	+ 'xspeed_after_purge',
	7509	+ array(
	7510	+ 'url' => null,
	7511	+ 'host' => '*',
	7512	+ 'path' => null,
	7513	+ 'cause' => $cause,
	7514	+ 'removed' => $count + $rest,
	7515	+ 'scope' => 'network',
	7516	+ 'intent' => 'assets',
	7517	+ 'urls' => array(),
	7518	+ )
	7519	+ );
	7520	+ } catch ( \Throwable $e ) {
	7521	+ self::log_purge_listener_error( 'xspeed_after_purge', $e );
	7522	+ }
	7523	+ }
	7524	+
	7525	+ return $count + $rest;
	7526	+ }
	7527	+
	7528	+ /**
	7529	+ * Delete this site's cached pages from both the flat and static trees.
	7530	+ *
	7531	+ * Extracted so the `assets` purge can reuse it: minified assets are a
	7532	+ * dependency of the cached HTML, so clearing them must clear the pages
	7533	+ * too or the pages are left referencing deleted files (#244).
	7534	+ *
	7535	+ * @return int Number of page entries removed.
	7536	+ */
	7537	+ private static function purge_pages(): int {
	7538	+ $count = 0;
	7539	+ // Scoped to this site — see purge_all(). (#6)
	7540	+ $scope = self::current_host_dir();
	7541	+ $flat_root = XSPEED_CACHE_DIR . '/' . $scope;
	7542	+ if ( is_dir( $flat_root ) ) {
	7543	+ foreach ( (array) glob( $flat_root . '/*.html' ) as $f ) {
	7544	+ wp_delete_file( $f );
	7545	+ ++$count;
	7546	+ }
	7547	+ foreach ( (array) glob( $flat_root . '/*.meta' ) as $m ) {
	7548	+ wp_delete_file( $m );
	7549	+ }
	7550	+ foreach ( (array) glob( $flat_root . '/*.br' ) as $b ) {
	7551	+ wp_delete_file( $b );
	7552	+ }
	7553	+ // `*.br` does not match `*.br.size`; a size record outliving its
	7554	+ // body would later be read against a DIFFERENT sibling's bytes.
	7555	+ foreach ( (array) glob( $flat_root . '/*.br.size' ) as $b ) {
	7556	+ wp_delete_file( $b );
	7557	+ }
	7558	+ }
	7559	+ $static_root = XSPEED_CACHE_STATIC_DIR . '/' . self::current_static_scope();
	7560	+ if ( is_dir( $static_root ) ) {
	7561	+ $count += self::rmtree_html( $static_root );
	7562	+ }
	7563	+
	7564	+ return $count;
	7565	+ }
	7566	+
	7567	+ /**
	7568	+ * A purge type this class does not own — a Pro or third-party module
	7569	+ * registered it via the `xspeed_purge_types` filter, so hand it off.
	7570	+ *
	7571	+ * @param string $type Purge-type slug.
	7572	+ * @param string $cause Who asked.
	7573	+ */
	7574	+ private static function purge_type_unhandled( string $type, string $cause ): int {
	7575	+ $event_sequence = self::$purge_event_sequence;
	7576	+ $hook = 'xspeed_purge_type_' . $type;
	7577	+ $has_handler = false !== has_action( $hook );
	7578	+ do_action( $hook );
	7579	+ self::record_partial_purge( $type, $cause, null );
	7580	+
	7581	+ // Announce, same as the types this class owns. Pro's "Purge Critical
	7582	+ // CSS" and "Purge Unused CSS" arrive here, and they change what a
	7583	+ // cached page CONTAINS — critical CSS is inlined into the HTML, so a
	7584	+ // server cache goes on serving pages with the old styles baked in.
	7585	+ // Fixing the three Free buttons and leaving these two silent left the
	7586	+ // same hole for the tier most likely to be using both plugins.
	7587	+ // (QA #348 round 2, issue 2)
	7588	+ //
	7589	+ // Unknown slugs must not turn into a site-wide purge merely because no
	7590	+ // handler exists. These are the response-changing Pro types Free knows;
	7591	+ // third parties can declare another through the filter. A registered
	7592	+ // handler plus this explicit response scope is the handled signal.
	7593	+ $scope = in_array( $type, array( 'critical-css', 'unused-css' ), true ) ? 'site' : 'none';
	7594	+ /**
	7595	+ * Declare whether a handled custom purge type changes cached responses.
	7596	+ *
	7597	+ * @since 1.2.3
	7598	+ * @param string $scope site/network/none.
	7599	+ * @param string $type Purge-type slug.
	7600	+ */
	7601	+ $scope = (string) apply_filters( 'xspeed_purge_type_response_scope', $scope, $type );
	7602	+ if ( $has_handler
	7603	+ && $event_sequence === self::$purge_event_sequence
	7604	+ && in_array( $scope, array( 'site', 'network' ), true )
	7605	+ ) {
	7606	+ self::announce_purge( $cause, 0, $scope, 'presentation' );
	7607	+ }
	7608	+
	7609	+ return 0;
	7610	+ }
	7611	+
	7612	+ /**
	7613	+ * Tell the server cache that a PARTIAL purge cleared cached responses.
	7614	+ *
	7615	+ * "Purge Page / Static Cache", "Purge CSS / JS Cache" and "Purge REST
	7616	+ * Cache" each delete cached RESPONSES for the whole site, so a cache in
	7617	+ * front of PHP is now serving copies xSpeed has just thrown away. Only
	7618	+ * "Purge All" announced itself, which left three of the four toolbar
	7619	+ * buttons doing exactly what this contract exists to prevent: clearing
	7620	+ * our copy while the server kept serving the stale one. The `assets` case
	7621	+ * was the sharpest — it deletes the minified bundles too, so LiteSpeed
	7622	+ * went on serving pages whose CSS and JS no longer exist. (QA #348)
	7623	+ *
	7624	+ * Sent as the full-purge shape (`url` null) because that is what happened:
	7625	+ * every cached page for this site went, not one address. `object` is not
	7626	+ * announced — flushing the object cache changes no rendered response a
	7627	+ * server cache could be holding.
	7628	+ *
	7629	+ * Public because Purge_Runner sweeps the local files itself, through
	7630	+ * purge_local(), rather than through purge_all() — so it has to announce
	7631	+ * on its own behalf or `wp xspeed purge` and the dashboard button clear
	7632	+ * our copy while LiteSpeed keeps serving the stale one.
	7633	+ *
	7634	+ * @param string $cause Who asked.
	7635	+ * @param int $removed Entries removed locally.
	7636	+ * @param string $scope Actionable adapter scope.
	7637	+ * @param string $intent Reason rendered responses changed.
	7638	+ */
	7639	+ public static function announce_purge( string $cause, int $removed, string $scope = 'site', string $intent = 'complete' ): void {
	7640	+ // Announcing is additive: the local sweep has already happened and
	7641	+ // succeeded. Notification must never be able to turn a working purge
	7642	+ // into a fatal, so anything the URL helpers do in an unusual context
	7643	+ // (early boot, a drop-in, a bare test harness) is contained here
	7644	+ // rather than propagating to the caller.
	7645	+ if ( ! function_exists( 'home_url' ) || ! function_exists( 'do_action' ) ) {
	7646	+ return;
	7647	+ }
	7648	+ try {
	7649	+ self::dispatch_purge_event(
	7650	+ 'xspeed_after_purge',
	7651	+ array(
	7652	+ 'url' => null,
	7653	+ 'host' => self::current_purge_host(),
	7654	+ 'path' => null,
	7655	+ 'cause' => $cause,
	7656	+ 'removed' => $removed,
	7657	+ 'scope' => $scope,
	7658	+ 'intent' => $intent,
	7659	+ 'urls' => array(),
	7660	+ )
	7661	+ );
	7662	+ } catch ( \Throwable $e ) {
	7663	+ self::log_purge_listener_error( 'xspeed_after_purge', $e );
	7664	+ }
	7665	+ }
	7666	+
	7667	+ /**
	7668	+ * Log a partial purge so the drill-down behind "Last purge" shows every
	7669	+ * clear, not only the full ones. Without this a site whose object cache
	7670	+ * is flushed on a schedule looks, from the log, like nothing happens.
	7671	+ *
	7672	+ * @param string $what Human label for the slice purged.
	7673	+ * @param string $cause Who asked.
	7674	+ * @param int|null $count Items removed, when countable.
	7675	+ */
	7676	+ private static function record_partial_purge( string $what, string $cause, ?int $count ): void {
	7677	+ $message = null === $count
	7678	+ ? sprintf(
	7679	+ /* translators: 1: what was purged, 2: cause of the purge. */
	7680	+ __( 'Purged %1$s (%2$s)', 'xspeed' ),
	7681	+ $what,
	7682	+ $cause
	7683	+ )
	7684	+ : sprintf(
	7685	+ /* translators: 1: what was purged, 2: cause of the purge, 3: number of files removed. */
	7686	+ __( 'Purged %1$s (%2$s) — %3$d file(s) removed', 'xspeed' ),
	7687	+ $what,
	7688	+ $cause,
	7689	+ $count
	7690	+ );
	7691	+
	7692	+ Activity_Log::record( 'cache_purged', $message, Activity_Log::INFO );
	7693	+
	7694	+ /*
	7695	+ * A partial purge is still a purge, and an edge in front of this site
	7696	+ * has to hear about it.
	7697	+ *
	7698	+ * "Purge Page / Static Cache" is always visible in the admin bar and
	7699	+ * clears every cached page for this site — the flat tree AND the
	7700	+ * static tree the generated nginx/Apache rules serve directly. It
	7701	+ * announced none of that: not `xspeed_after_purge_all`, which only
	7702	+ * purge_all() fires, and not the scoped actions. A CDN told to hold
	7703	+ * those pages went on serving the ones xSpeed had just deleted, for
	7704	+ * whatever lifetime it was given.
	7705	+ *
	7706	+ * Scope is `site` only for the two types that clear rendered HTML.
	7707	+ * An object-cache flush or a REST purge removes nothing an edge is
	7708	+ * holding, and announcing those as a site purge would have a CDN
	7709	+ * drop its whole cache every time a scheduled flush ran — worse than
	7710	+ * the silence this replaces. A type registered by another plugin
	7711	+ * through `xspeed_purge_types` is unknown here, so it says nothing
	7712	+ * rather than guessing.
	7713	+ *
	7714	+ * Not gated on `$count`, for the reason spelled out in purge_url():
	7715	+ * an empty local tree is not evidence that the edge is empty, and
	7716	+ * "Purge Page / Static Cache" with nothing left locally is precisely
	7717	+ * what someone clicks when the page they are looking at is stale.
	7718	+ * Answering that with silence made the button appear broken.
	7719	+ *
	7720	+ * That announcement is now `announce_purge()`'s, called beside this
	7721	+ * by the same callers (`page`, `assets`, `REST responses`). This
	7722	+ * function went back to being what its name says: a log entry. It
	7723	+ * used to publish as well, which double-fired every partial purge and
	7724	+ * — worse — announced `scope: none` for types #348's contract
	7725	+ * requires to stay silent about.
	7726	+ */
	7727	+ }
	7728	+
	7729	+ /**
	7730	+ * Clear the static tree only, leaving the flat cache in place.
	7731	+ *
	7732	+ * A narrower purge_all() for the case where only the web-server tree can
	7733	+ * be wrong: its files are keyed by `{host}{path}` and nothing else, so a
	7734	+ * response filed under the wrong path poisons it while the flat cache —
	7735	+ * keyed by cache_key(), discriminators included — stays correct. Avoids
	7736	+ * throwing away Critical CSS, minified bundles and the object cache to
	7737	+ * fix a static-only problem.
	7738	+ *
	7739	+ * @return int Number of index.html files removed.
	7740	+ */
	7741	+ public static function purge_static_tree(): int {
	7742	+ return self::rmtree_html( XSPEED_CACHE_STATIC_DIR );
	7743	+ }
	7744	+
	7745	+ /**
901	7746	* Recursively delete every `index.html` (and its precompressed
902	7747	* `index.html.br` sibling, if the Pro Brotli module wrote one) plus
903	7748	* empty directories inside the static-cache tree. Used by purge_all().
904	7749	* Returns the number of .html files removed so purge stats stay accurate
		@@ -904,8 +7749,24 @@
904	7749	* Returns the number of .html files removed so purge stats stay accurate
905	7750	* across the flat + static caches — .br siblings are not counted
906	7751	* (they're encodings of a page, not pages).
907	7752	*/
	7753	+ /**
	7754	+ * Delete a cache file, adding its size to the current sweep's byte
	7755	+ * total. filesize() is silenced and re-checked because the file can
	7756	+ * vanish between the glob and the unlink — a concurrent purge, or the
	7757	+ * cache GC — and a warning there would be noise, not news.
	7758	+ *
	7759	+ * @param string $file Absolute path inside the cache tree.
	7760	+ */
	7761	+ private static function sweep_delete( string $file ): void {
	7762	+ $size = @filesize( $file ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- the file may be gone already; see docblock.
	7763	+ if ( is_int( $size ) ) {
	7764	+ self::$sweep_bytes += $size;
	7765	+ }
	7766	+ wp_delete_file( $file );
	7767	+ }
	7768	+
908	7769	private static function rmtree_html( string $dir ): int {
909	7770	if ( ! is_dir( $dir ) ) {
910	7771	return 0;
911	7772	}
		@@ -929,14 +7790,22 @@
929	7790	@rmdir( $path );
930	7791	continue;
931	7792	}
932	7793	if ( substr( $entry, -5 ) === '.html' ) {
933		- wp_delete_file( $path );
	7794	+ self::sweep_delete( $path );
934	7795	++$removed;
935		- } elseif ( substr( $entry, -3 ) === '.br' ) {
936		- // Precompressed sibling (index.html.br). Remove it too so a
937		- // purge doesn't orphan stale Brotli bodies. Not counted.
938		- wp_delete_file( $path );
	7796	+ } elseif ( self::EXPIRES_MARKER === $entry ) {
	7797	+ // store_static()'s deadline for a nonce page. Left behind, it
	7798	+ // kept every such folder from being removed, and the failed
	7799	+ // rmdir warned once per folder: Query Monitor turned those
	7800	+ // into enough response headers to 502 a post save (#636).
	7801	+ self::sweep_delete( $path );
	7802	+ } elseif ( substr( $entry, -3 ) === '.br' || substr( $entry, -8 ) === '.br.size' ) {
	7803	+ // Precompressed sibling (index.html.br) and the record of its
	7804	+ // length. Remove both so a purge doesn't orphan stale Brotli
	7805	+ // bodies, or a size record that would later be read against a
	7806	+ // different sibling's bytes. Not counted.
	7807	+ self::sweep_delete( $path );
939	7808	}
940	7809	}
941	7810	return $removed;
942	7811	}
		@@ -953,25 +7822,42 @@
953	7822	}
954	7823	}
955	7824
956	7825	/**
	7826	+ * The raw xspeed_stats option as an array. Keys currently in use:
	7827	+ * 'last_purge', 'last_gc', 'gc_removed', 'gc_removed_total'.
	7828	+ */
	7829	+ public static function get_stats_option(): array {
	7830	+ $stats = get_option( 'xspeed_stats', array() );
	7831	+ return is_array( $stats ) ? $stats : array();
	7832	+ }
	7833	+
	7834	+ /**
957	7835	* Persist stats with autoload disabled — stats are only read in admin
958	7836	* contexts, so there is no reason to inflate every frontend request's
959	7837	* `wp_load_alloptions()` payload.
	7838	+ *
	7839	+ * MERGES into whatever is already stored. It used to overwrite, which
	7840	+ * was harmless while `last_purge` was the only key — with the GC keys
	7841	+ * alongside it, a purge would have wiped the GC history and vice versa.
960	7842	*/
961		- private static function update_stats( array $stats ) {
962		- if ( false === get_option( 'xspeed_stats' ) ) {
	7843	+ public static function update_stats( array $stats ) {
	7844	+ if ( false === get_option( 'xspeed_stats', false ) ) {
963	7845	add_option( 'xspeed_stats', $stats, '', 'no' );
964	7846	return;
965	7847	}
966		- update_option( 'xspeed_stats', $stats );
	7848	+ update_option( 'xspeed_stats', array_merge( self::get_stats_option(), $stats ) );
967	7849	}
968	7850
969	7851	public static function get_stats() {
970	7852	$count = 0;
971	7853	$size = 0;
972		- if ( is_dir( XSPEED_CACHE_DIR ) ) {
973		- $files = glob( XSPEED_CACHE_DIR . '/*.html' );
	7854	+ // This site's entries only — on multisite the tree is shared, so an
	7855	+ // unscoped count reported the whole network's pages on every
	7856	+ // subsite's dashboard. (#6)
	7857	+ $flat_root = XSPEED_CACHE_DIR . '/' . self::current_host_dir();
	7858	+ if ( is_dir( $flat_root ) ) {
	7859	+ $files = glob( $flat_root . '/*.html' );
974	7860	if ( $files ) {
975	7861	$count = count( $files );
976	7862	foreach ( $files as $f ) {
977	7863	$size += filesize( $f );
		@@ -994,8 +7880,12 @@
994	7880	Hit_Counter::collect_server_log_hits();
995	7881
996	7882	$stats = get_option( 'xspeed_stats', array() );
997	7883	$totals = Hit_Counter::totals_24h();
	7884	+ // One read of the ground truth for both fields below: it costs a
	7885	+ // stat of advanced-cache.php and a tokenize of wp-config.php, and
	7886	+ // this runs on every dashboard poll.
	7887	+ $serving = self::page_cache_operational();
998	7888	return array(
999	7889	'cached_pages' => $count,
1000	7890	'cache_size' => $size,
1001	7891	'last_purge' => isset( $stats['last_purge'] ) ? (int) $stats['last_purge'] : 0,
		@@ -1004,21 +7894,146 @@
1004	7894	// CacheHero stat grid + the Health module's panel.
1005	7895	'hits_24h' => $totals['hits'],
1006	7896	'misses_24h' => $totals['misses'],
1007	7897	'hit_ratio' => $totals['ratio'],
	7898	+ // Requests kept OUT of the ratio (404s + bots) — surfaced as its own
	7899	+ // "absorbed N scanner/bot requests" line rather than distorting the
	7900	+ // cache-performance number. (#118)
	7901	+ 'excluded_24h' => $totals['excluded'],
	7902	+ // True when an edge cache (Cloudflare) fronts the origin, so hits are
	7903	+ // absorbed before reaching PHP. The dashboard labels the ratio
	7904	+ // "origin-layer only" instead of implying it's the full picture. (#118)
	7905	+ 'edge_cache' => self::edge_cache_detected(),
	7906	+ // LiteSpeed Static Fast Path (#509): the web server serves hits
	7907	+ // with no PHP, no way to tag them, and no way to count them. The
	7908	+ // dashboard labels the ratio as PHP-layer only so a low number
	7909	+ // reads as the trade the user chose, not a fault.
	7910	+ //
	7911	+ // rewrite_installed() is part of the condition (QA on #513): when
	7912	+ // the .htaccess write failed (read-only file), hits still take
	7913	+ // the drop-in path and ARE counted — the disclosure would be the
	7914	+ // opposite of the truth. Health carries the "block missing"
	7915	+ // warning for that state; this flag only speaks when static
	7916	+ // serving is genuinely in effect.
	7917	+ 'static_hits_uncounted' => (
	7918	+ Server::LITESPEED === Server::type()
	7919	+ && ! empty( Settings::get()['cache_enabled'] )
	7920	+ && self::static_rewrite_allowed()
	7921	+ && self::rewrite_installed()
	7922	+ ),
	7923	+ /*
	7924	+ * Whether the page cache is actually SERVING, as opposed to
	7925	+ * switched on in settings. The hero read the setting alone and
	7926	+ * announced "Active — serving cached HTML"; a site whose
	7927	+ * advanced-cache.php had been taken over by another cache plugin
	7928	+ * got that line while every response carried
	7929	+ * `X-XSpeed-Cache: BYPASS`. The setting is the user's intent;
	7930	+ * this is the outcome, and the dashboard needs both to explain
	7931	+ * the difference.
	7932	+ */
	7933	+ 'page_cache_serving' => $serving,
	7934	+ /*
	7935	+ * Why not, when intent and outcome disagree. Only computed in
	7936	+ * that state — the detector sweep behind it is far more work than
	7937	+ * a stats call should do on an ordinary healthy site.
	7938	+ */
	7939	+ 'page_cache_blocked_reason' => ( ! $serving && ! empty( Settings::get()['cache_enabled'] ) )
	7940	+ ? ( self::acquisition_blocker() ?? self::not_serving_reason() )
	7941	+ : null,
1008	7942	);
1009	7943	}
1010	7944
1011	7945	/**
1012		- * Apply the user's enable/disable choice. Called only from the REST
1013		- * toggle endpoint, which is gated by current_user_can( 'manage_options' )
1014		- * and a verified REST nonce. This is the only place the drop-in and
1015		- * the WP_CACHE constant are written — they MUST NOT happen on
1016		- * register_activation_hook (WordPress.org review requirement).
	7946	+ * Why the cache is not serving, when nothing REFUSES to enable it.
1017	7947	*
	7948	+ * acquisition_blocker() answers "may we take the field", and since a
	7949	+ * foreign drop-in became takeable it answers null on a site where another
	7950	+ * plugin is nonetheless holding that file. Intent and outcome still
	7951	+ * disagree there, and the dashboard was left reporting the symptom -- not
	7952	+ * serving -- with no reason under it, which is exactly the state a user
	7953	+ * cannot act on.
	7954	+ *
	7955	+ * So this names the holder and says what to do: enabling takes it over.
	7956	+ */
	7957	+ private static function not_serving_reason(): ?string {
	7958	+ $owner = self::dropin_owner();
	7959	+ if ( self::DROPIN_FOREIGN !== $owner && self::DROPIN_UNREADABLE !== $owner ) {
	7960	+ return null;
	7961	+ }
	7962	+
	7963	+ if ( self::DROPIN_UNREADABLE === $owner ) {
	7964	+ return __( 'advanced-cache.php cannot be read, so xSpeed cannot tell whose page cache is installed.', 'xspeed' );
	7965	+ }
	7966	+
	7967	+ $label = Page_Cache_Detector::dropin_owner_label();
	7968	+ return $label
	7969	+ ? sprintf(
	7970	+ /* translators: %s: the page-caching plugin that owns advanced-cache.php. */
	7971	+ __( '%s is serving the page cache. Turn the xSpeed cache off and on again to take it over.', 'xspeed' ),
	7972	+ $label
	7973	+ )
	7974	+ : __( 'Another plugin is serving the page cache. Turn the xSpeed cache off and on again to take it over.', 'xspeed' );
	7975	+ }
	7976	+
	7977	+ /**
	7978	+ * Whether the current request should be kept OUT of the cache hit/miss
	7979	+ * ratio: a genuine 404, or a known bot / scanner. Runs at template_redirect
	7980	+ * time, so is_404() is resolved. (#118)
	7981	+ */
	7982	+ private static function miss_is_excluded(): bool {
	7983	+ if ( function_exists( 'is_404' ) && is_404() ) {
	7984	+ return true;
	7985	+ }
	7986	+ // A marked request is ours whatever its UA says: a renamed warmer,
	7987	+ // or a probe that has to send a browser's UA.
	7988	+ if ( Self_Traffic::request_is_marked() ) {
	7989	+ return true;
	7990	+ }
	7991	+ $ua = isset( $_SERVER['HTTP_USER_AGENT'] )
	7992	+ ? sanitize_text_field( wp_unslash( (string) $_SERVER['HTTP_USER_AGENT'] ) )
	7993	+ : '';
	7994	+ return Hit_Counter::is_bot_ua( $ua );
	7995	+ }
	7996	+
	7997	+ /**
	7998	+ * Whether an edge cache fronts this origin, so an unknown share of hits
	7999	+ * is served there and never counted here — which makes the origin ratio a
	8000	+ * partial view the dashboard has to label as such. (#118)
	8001	+ *
	8002	+ * This used to mean "the Cloudflare module is switched on", which answered
	8003	+ * no for every site fronted by anything else, and no for a site on
	8004	+ * Cloudflare that had never opened our Cloudflare panel. Both of those
	8005	+ * sites had their ratio presented as the whole story. Edge_Provider knows
	8006	+ * better and knows it per request, so ask it.
	8007	+ */
	8008	+ private static function edge_cache_detected(): bool {
	8009	+ return Edge_Provider::NONE !== Edge_Provider::detect()['confidence'];
	8010	+ }
	8011	+
	8012	+ /**
	8013	+ * Apply the user's enable/disable choice. Called from the REST toggle
	8014	+ * endpoint, which is gated by current_user_can( 'manage_options' ) and
	8015	+ * a verified REST nonce.
	8016	+ *
	8017	+ * This is the only path that ENABLES caching — a drop-in is never
	8018	+ * created for a user who hasn't opted in, which is the guideline that
	8019	+ * matters (a plugin must not install drop-ins or edit wp-config.php
	8020	+ * on a fresh activation). RESTORING the drop-in for a site that
	8021	+ * already has cache_enabled = true is a different act and is handled
	8022	+ * by restore_dropin_if_enabled() on activation and auto_heal() at
	8023	+ * runtime; without it every plugin update silently un-caches the site.
	8024	+ *
	8025	+ * Enabling is gated on acquisition_blocker(): if another plugin owns the
	8026	+ * drop-in, or WP_CACHE is written in a form we must not rewrite, nothing
	8027	+ * is written and the returned state carries `blocked` + a reason the
	8028	+ * caller can show. Callers must persist `cache_enabled` from the returned
	8029	+ * `enabled`, never from what they asked for.
	8030	+ *
1018	8031	* @param bool $enable User's choice.
1019	8032	* @return array{
1020	8033	* enabled: bool,
	8034	+ * blocked: bool,
	8035	+ * blocked_reason: ?string,
1021	8036	* dropin_installed: bool,
1022	8037	* wp_cache_constant: bool,
1023	8038	* wp_config_writable: bool,
1024	8039	* manual_snippet: ?string
		@@ -1023,29 +8038,294 @@
1023	8038	* wp_config_writable: bool,
1024	8039	* manual_snippet: ?string
1025	8040	* }
1026	8041	*/
1027		- public static function toggle( $enable ) {
	8042	+ public static function toggle( $enable, bool $consented = true ) {
	8043	+ Page_Cache_Detector::invalidate();
	8044	+ $expected = Page_Cache_Detector::inspect()['revision'];
	8045	+ /** Diagnostic seam; changing the expected revision can only force a safe refusal. */
	8046	+ $expected = (string) apply_filters( 'xspeed_page_cache_expected_revision', $expected );
	8047	+ $lock = self::page_cache_lock();
	8048	+ if ( ! is_resource( $lock ) ) {
	8049	+ return self::blocked_toggle_state( __( 'Could not lock page-cache ownership. Try again.', 'xspeed' ) );
	8050	+ }
	8051	+ $changed = false;
	8052	+ try {
	8053	+ Page_Cache_Detector::invalidate();
	8054	+ $fresh = Page_Cache_Detector::inspect()['revision'];
	8055	+ if ( ! hash_equals( (string) $expected, (string) $fresh ) ) {
	8056	+ return self::blocked_toggle_state( __( 'Page-cache ownership changed while xSpeed was checking it. Nothing was changed; try again.', 'xspeed' ) );
	8057	+ }
	8058	+ $before = self::page_cache_fingerprint();
	8059	+ $state = self::toggle_unlocked( (bool) $enable, $consented );
	8060	+ $changed = empty( $state['blocked'] ) && self::page_cache_fingerprint() !== $before;
	8061	+ return $state;
	8062	+ } finally {
	8063	+ flock( $lock, LOCK_UN );
	8064	+ fclose( $lock );
	8065	+
	8066	+ /*
	8067	+ * Announce the change to anything caching in front of us.
	8068	+ *
	8069	+ * Turning the page cache on or off changes what every URL on this
	8070	+ * site returns, and a CDN holding renders made under the old state
	8071	+ * goes on serving them for their whole lifetime. Nothing told it.
	8072	+ * OFF is the less obvious half and matters as much: the edge
	8073	+ * otherwise keeps serving pages from a cache the site no longer
	8074	+ * has.
	8075	+ *
	8076	+ * Only when something actually changed. A refused toggle wrote
	8077	+ * nothing — that is the whole point of the refusal — and purging
	8078	+ * after it would announce a change that did not happen. Nor does a
	8079	+ * toggle that found the cache already in the state it asked for:
	8080	+ * auto_heal() re-enables on every admin_init, and gating on "not
	8081	+ * refused" alone made every wp-admin page load empty the page
	8082	+ * cache and purge the edge (QA, 2026-09-23). The fingerprint is
	8083	+ * compared instead, so restoring a stripped drop-in still counts.
	8084	+ *
	8085	+ * After the writes and OUTSIDE the lock. Before them, a purge
	8086	+ * would repopulate from the state we are in the middle of leaving,
	8087	+ * which is how a "purge didn't work" report is born; inside them,
	8088	+ * it would hold single-occupancy ownership for the length of a
	8089	+ * filesystem sweep.
	8090	+ */
	8091	+ if ( $changed ) {
	8092	+ /*
	8093	+ * On shutdown, not inline. `purge_all()` sweeps the cache
	8094	+ * directory and fires the purge actions, and a listener on
	8095	+ * those can make an HTTP call to an edge — so running it here
	8096	+ * would make the toggle as slow as the sweep and couple its
	8097	+ * response to a third party. The Cloudflare Enterprise purge
	8098	+ * queue already defers for the same reason.
	8099	+ *
	8100	+ * Still after the writes: shutdown runs at the end of THIS
	8101	+ * request, with the new state on disk.
	8102	+ */
	8103	+ add_action(
	8104	+ 'shutdown',
	8105	+ static function () {
	8106	+ self::purge_all( 'page cache toggled' );
	8107	+ },
	8108	+ 20
	8109	+ );
	8110	+ }
	8111	+ }
	8112	+ }
	8113	+
	8114	+ /** Run the page-cache mutation while toggle() owns the scoped lock. */
	8115	+ /**
	8116	+ * @param bool $consented The user asked for this in the dashboard, so a
	8117	+ * foreign drop-in may be taken over. False on the
	8118	+ * unattended paths, which stand down instead.
	8119	+ */
	8120	+ /**
	8121	+ * What the page cache looks like on disk and in wp-config, as one string.
	8122	+ *
	8123	+ * `toggle()` compares it before and after its writes to tell a real ON/OFF
	8124	+ * flip, or a repaired drop-in, from a call that found everything already
	8125	+ * as asked. Only the latter must not announce a purge.
	8126	+ */
	8127	+ private static function page_cache_fingerprint(): string {
	8128	+ $dropin = self::read_file( WP_CONTENT_DIR . '/advanced-cache.php' );
	8129	+ return md5(
	8130	+ ( null === $dropin ? "\0none" : md5( $dropin ) )
	8131	+ . '|' . self::wp_cache_define_state()
	8132	+ . '|' . ( self::rewrite_installed() ? '1' : '0' )
	8133	+ . '|' . ( self::page_cache_operational() ? '1' : '0' )
	8134	+ );
	8135	+ }
	8136	+
	8137	+ private static function toggle_unlocked( bool $enable, bool $consented = true ) {
1028	8138	$enable = (bool) $enable;
1029	8139
1030	8140	if ( $enable ) {
1031		- $dropin_ok = self::install_dropin();
1032		- $wp_config_ok = self::set_wp_cache_constant( true );
	8141	+ /*
	8142	+ * Preflight. The drop-in and the WP_CACHE define are shared,
	8143	+ * single-occupancy state; if we do not own them, no part of this
	8144	+ * runs — not the drop-in, not wp-config.php, not the rewrite
	8145	+ * block. Refusing whole is the point: a partial enable leaves the
	8146	+ * site claiming a cache it cannot serve.
	8147	+ *
	8148	+ * Every caller routes through here (REST, onboarding, MCP, CLI,
	8149	+ * the optimize runner, Pro's migration), so the gate lives here
	8150	+ * rather than being re-implemented at each entry point.
	8151	+ *
	8152	+ * Except when there is nothing to acquire. A site where we
	8153	+ * already own the drop-in and are already serving is being asked
	8154	+ * to stay as it is, and the gate answers a different question —
	8155	+ * "is the field free to take" — which a merely ACTIVE competitor
	8156	+ * makes false. So "make sure caching is on", from an AI agent,
	8157	+ * the optimize runner or Pro's migration, came back as a refusal
	8158	+ * telling the user to deactivate a plugin on a site that was
	8159	+ * caching perfectly. The dashboard never saw it, because nobody
	8160	+ * presses Enable on a cache that is already enabled.
	8161	+ *
	8162	+ * Only the GATE is skipped. The writes below still run, and every
	8163	+ * one of them is individually idempotent — which matters, because
	8164	+ * this is the path CacheModule re-bakes the drop-in through when
	8165	+ * an exclusion rule or the TTL changes (#240, #251), and the path
	8166	+ * auto_heal() restores a stripped WP_CACHE through. Returning
	8167	+ * early here left both of those doing nothing at all, silently,
	8168	+ * on exactly the healthy sites this branch is about.
	8169	+ */
	8170	+ $reasserting = self::page_cache_operational() && self::DROPIN_XSPEED === self::dropin_owner();
	8171	+ $blocker = $reasserting ? null : self::acquisition_blocker();
	8172	+
	8173	+ /*
	8174	+ * Taking over another plugin's drop-in needs the user to have
	8175	+ * asked for it. On the dashboard they did -- they clicked the
	8176	+ * switch, having been told whose file it is. The UNATTENDED
	8177	+ * callers have no such click: restore_dropin_if_enabled() runs
	8178	+ * after a plugin update and auto_heal() on an admin page load,
	8179	+ * both from nothing more than `cache_enabled` still being true.
	8180	+ *
	8181	+ * A competitor installed since that flag was set would have its
	8182	+ * page cache seized by a background repair, which is the silent
	8183	+ * acquisition this plugin refuses to perform. So those callers
	8184	+ * pass $consented = false and stand down instead.
	8185	+ */
	8186	+ if ( null === $blocker && ! $consented && self::DROPIN_FOREIGN === self::dropin_owner() ) {
	8187	+ // Name the owner. This string is rendered by host plugins
	8188	+ // through Host::enable_page_cache(), and an unnamed refusal
	8189	+ // is what made every host invent its own explanation.
	8190	+ $owner_label = Page_Cache_Detector::dropin_owner_label();
	8191	+ return self::blocked_toggle_state(
	8192	+ $owner_label
	8193	+ ? sprintf(
	8194	+ /* translators: %s: the page-caching plugin that owns advanced-cache.php. */
	8195	+ __( '%s owns advanced-cache.php, so xSpeed left it alone. Enable the cache from the xSpeed dashboard to take it over.', 'xspeed' ),
	8196	+ $owner_label
	8197	+ )
	8198	+ : __( 'Another plugin owns advanced-cache.php, so xSpeed left it alone. Enable the cache from the xSpeed dashboard to take it over.', 'xspeed' )
	8199	+ );
	8200	+ }
	8201	+ if ( null !== $blocker ) {
	8202	+ Activity_Log::record(
	8203	+ 'cache_enable_blocked',
	8204	+ 'Cache not enabled — ' . $blocker,
	8205	+ Activity_Log::WARN
	8206	+ );
	8207	+
	8208	+ return self::blocked_toggle_state( $blocker );
	8209	+ }
	8210	+
	8211	+ $dropin_path = WP_CONTENT_DIR . '/advanced-cache.php';
	8212	+ $config_path = self::wp_config_path();
	8213	+ $dropin_before = file_exists( $dropin_path ) ? self::read_file( $dropin_path ) : null;
	8214	+ $config_before = '' !== $config_path ? self::read_file( $config_path ) : null;
	8215	+ $dropin_ok = self::install_dropin();
	8216	+ if ( ! $dropin_ok ) {
	8217	+ $partial = self::read_file( $dropin_path );
	8218	+ if ( is_string( $partial ) && xspeed_has_canonical_dropin_signature( $partial ) ) {
	8219	+ self::rollback_page_cache_artifacts( $dropin_path, $dropin_before, $partial, $config_path, $config_before, null );
	8220	+ }
	8221	+ /*
	8222	+ * Preflight said the field was clear, so this is a filesystem
	8223	+ * failure (or a drop-in that appeared in between). Without the
	8224	+ * drop-in there is no cache to enable, and persisting
	8225	+ * cache_enabled anyway is what produced sites reporting a
	8226	+ * healthy cache while serving every request uncached.
	8227	+ */
	8228	+ $reason = __( 'Could not write wp-content/advanced-cache.php. Check filesystem permissions.', 'xspeed' );
	8229	+ Activity_Log::record(
	8230	+ 'cache_enable_blocked',
	8231	+ 'Cache not enabled — ' . $reason,
	8232	+ Activity_Log::WARN
	8233	+ );
	8234	+
	8235	+ return array(
	8236	+ 'enabled' => false,
	8237	+ 'blocked' => true,
	8238	+ 'blocked_reason' => $reason,
	8239	+ 'dropin_installed' => false,
	8240	+ 'wp_cache_constant' => false,
	8241	+ 'rewrite_installed' => false,
	8242	+ 'wp_config_writable' => self::wp_config_writable(),
	8243	+ 'manual_snippet' => null,
	8244	+ 'nginx_snippet' => self::nginx_snippet(),
	8245	+ 'nginx_server_block' => self::full_nginx_server_block(),
	8246	+ );
	8247	+ }
	8248	+
	8249	+ $dropin_written = self::read_file( $dropin_path );
	8250	+ self::set_wp_cache_constant( true );
	8251	+ $config_written = '' !== $config_path ? self::read_file( $config_path ) : null;
	8252	+ Page_Cache_Detector::invalidate();
	8253	+ $dropin_ours = self::DROPIN_XSPEED === self::dropin_owner();
	8254	+ $constant_state = self::wp_cache_define_state();
	8255	+ $constant_ok = 'true' === $constant_state;
	8256	+
	8257	+ /*
	8258	+ * A wp-config.php we cannot write at all is a supported state, not
	8259	+ * a failed transaction. Plenty of managed hosts ship the file
	8260	+ * read-only; there the drop-in is ours and installed, the cache
	8261	+ * works the moment WP_CACHE exists, and the one line to paste
	8262	+ * comes back as `manual_snippet`. Rolling back instead left those
	8263	+ * hosts unable to turn the page cache on by any route — including
	8264	+ * when the user had already pasted the define, since the write
	8265	+ * fails on an unwritable file whatever value is already there.
	8266	+ *
	8267	+ * `undefined` ONLY. `false` looks eligible — this method would
	8268	+ * have rewritten it — but the snippet we hand back cannot work
	8269	+ * there: the file already says `define( 'WP_CACHE', false )`, the
	8270	+ * first define() call wins, and a user who pastes our line via
	8271	+ * FTP ends up with a cache that never serves AND a `duplicate`
	8272	+ * wp-config that blocks every future toggle in both directions.
	8273	+ * They have to edit the existing line, which means refusing here
	8274	+ * and saying so. `duplicate` and `dynamic` are refused by
	8275	+ * acquisition_blocker() before we get here, and if one appears in
	8276	+ * the race window it must still fail closed.
	8277	+ */
	8278	+ $manual_mode = ! $constant_ok
	8279	+ && 'undefined' === $constant_state
	8280	+ && ! self::can_write_wp_config();
	8281	+
	8282	+ if ( ! $dropin_ours || ( ! $constant_ok && ! $manual_mode ) ) {
	8283	+ if ( ! self::can_write_wp_config() ) {
	8284	+ $reason = 'false' === $constant_state
	8285	+ ? __( "wp-config.php is not writable and already contains define( 'WP_CACHE', false ). Change that line to true — adding a second one would leave the cache off and block xSpeed from changing it again.", 'xspeed' )
	8286	+ : __( 'xSpeed could not verify the complete page-cache write, and wp-config.php is not writable. Its changes were rolled back.', 'xspeed' );
	8287	+ } else {
	8288	+ $reason = __( 'xSpeed could not verify the complete page-cache write. Its changes were rolled back.', 'xspeed' );
	8289	+ }
	8290	+ self::rollback_page_cache_artifacts( $dropin_path, $dropin_before, $dropin_written, $config_path, $config_before, $config_written );
	8291	+ return self::blocked_toggle_state( $reason );
	8292	+ }
	8293	+ $wp_config_ok = $constant_ok;
1033	8294	$rewrite_ok = self::install_rewrite();
1034	8295	self::ensure_hits_log_file();
1035	8296	self::sync_mobile_flag();
1036	8297	$snippet = $wp_config_ok ? null : "define( 'WP_CACHE', true );";
	8298	+ Settings::update( array( 'cache_enabled' => true ) );
	8299	+ if ( empty( Settings::get()['cache_enabled'] ) ) {
	8300	+ self::remove_rewrite();
	8301	+ self::rollback_page_cache_artifacts( $dropin_path, $dropin_before, $dropin_written, $config_path, $config_before, $config_written );
	8302	+ delete_option( 'xspeed_page_cache_ownership_receipt' );
	8303	+ return self::blocked_toggle_state( __( 'xSpeed could not save the page-cache setting. Its file changes were rolled back.', 'xspeed' ) );
	8304	+ }
1037	8305
1038		- Activity_Log::record(
1039		- 'cache_enabled_event',
1040		- $wp_config_ok
1041		- ? 'Cache enabled. Drop-in installed, WP_CACHE constant set.'
1042		- : 'Cache enabled. Drop-in installed; wp-config.php not writable — add the WP_CACHE snippet manually.',
1043		- $wp_config_ok ? Activity_Log::SUCCESS : Activity_Log::WARN
1044		- );
	8306	+ /*
	8307	+ * Only when this call actually changed something. auto_heal() runs
	8308	+ * the enable transaction on every admin_init, and an unconditional
	8309	+ * entry filled the 50-slot log with identical "Cache enabled" lines
	8310	+ * within 50 wp-admin page loads, evicting every real event — plus
	8311	+ * an option write per admin request. The sentence is also false
	8312	+ * when nothing was installed.
	8313	+ */
	8314	+ if ( $dropin_written !== $dropin_before || $config_written !== $config_before ) {
	8315	+ Activity_Log::record(
	8316	+ 'cache_enabled_event',
	8317	+ $wp_config_ok
	8318	+ ? 'Cache enabled. Drop-in installed, WP_CACHE constant set.'
	8319	+ : 'Cache enabled. Drop-in installed; wp-config.php not writable — add the WP_CACHE snippet manually.',
	8320	+ $wp_config_ok ? Activity_Log::SUCCESS : Activity_Log::WARN
	8321	+ );
	8322	+ }
1045	8323
1046	8324	return array(
1047	8325	'enabled' => true,
	8326	+ 'blocked' => false,
	8327	+ 'blocked_reason' => null,
1048	8328	'dropin_installed' => (bool) $dropin_ok,
1049	8329	'wp_cache_constant' => (bool) $wp_config_ok,
1050	8330	'rewrite_installed' => (bool) $rewrite_ok,
1051	8331	'wp_config_writable' => self::wp_config_writable(),
		@@ -1058,26 +8338,168 @@
1058	8338	'nginx_server_block' => self::full_nginx_server_block(),
1059	8339	);
1060	8340	}
1061	8341
	8342	+ /*
	8343	+ * Whose advanced-cache.php is on disk decides how much of the disable
	8344	+ * below may run. Read it once, before anything is touched.
	8345	+ */
	8346	+ $owner = self::dropin_owner();
	8347	+ $not_ours = self::DROPIN_FOREIGN === $owner || self::DROPIN_UNREADABLE === $owner;
	8348	+ if ( ! self::set_wp_cache_constant( false ) ) {
	8349	+ /*
	8350	+ * The mirror of the enable path. A wp-config.php nobody can write
	8351	+ * does not trap the user in a cache they turned off: WP_CACHE on
	8352	+ * its own does nothing once advanced-cache.php is gone, and core
	8353	+ * simply skips the missing drop-in. Refusing here left the
	8354	+ * read-only managed hosts able to enable the page cache and never
	8355	+ * able to disable it again.
	8356	+ *
	8357	+ * A drop-in that is not ours reaches the same conclusion by a
	8358	+ * different road. WP_CACHE is then the switch for THEIR cache, so
	8359	+ * set_wp_cache_constant() refuses it — correctly, and permanently,
	8360	+ * because nothing the user does to xSpeed will make that file ours
	8361	+ * again. Treating that refusal as a failed disable was a trap with
	8362	+ * no exit: install any competing cache plugin while xSpeed's cache
	8363	+ * was on, and xSpeed's toggle could never be turned off again,
	8364	+ * while the dashboard went on claiming a cache that was serving
	8365	+ * nothing. Turning xSpeed off is entirely within our own state —
	8366	+ * our setting, our rewrite block — so it proceeds, and their
	8367	+ * constant and their file are left exactly as they are.
	8368	+ */
	8369	+ /*
	8370	+ * Every reason set_wp_cache_constant() refuses is structural
	8371	+ * except one, and the exception is the only one worth blocking
	8372	+ * on. It will not touch a constant it cannot prove is ours; it
	8373	+ * will not rewrite a define it cannot read as a literal —
	8374	+ * duplicate, dynamic, or inside a conditional; and it cannot
	8375	+ * write a file the filesystem will not let it write. None of
	8376	+ * those improve on a retry, and all of them leave a WP_CACHE
	8377	+ * that does nothing once our drop-in is gone. What is left — our
	8378	+ * own constant, in a shape we can rewrite, in a file we can
	8379	+ * write, and the write still failed — is a real I/O failure, and
	8380	+ * that one still refuses so the user is not told a cache was
	8381	+ * turned off while it goes on serving.
	8382	+ *
	8383	+ * The proof, not the drop-in, is the test. A user who pasted our
	8384	+ * manual snippet on a locked-down host has a WP_CACHE line with
	8385	+ * no receipt on it; if their drop-in later goes missing, we can
	8386	+ * never prove that line is ours, so refusing left the toggle
	8387	+ * stuck on with no way out but enabling first and disabling
	8388	+ * again. Nothing loads a drop-in that is not there, so the line
	8389	+ * is inert either way and the disable proceeds without it.
	8390	+ */
	8391	+ $leave_it = ! self::wp_cache_define_is_ours_to_remove( $owner )
	8392	+ || ! in_array( self::wp_cache_define_state(), array( 'true', 'false', 'undefined' ), true )
	8393	+ || ! self::can_write_wp_config();
	8394	+ if ( ! $leave_it ) {
	8395	+ return self::blocked_toggle_state( __( 'xSpeed could not safely remove its WP_CACHE setting. The cache remains enabled.', 'xspeed' ) );
	8396	+ }
	8397	+ }
1062	8398	self::remove_dropin();
1063		- self::set_wp_cache_constant( false );
	8399	+ if ( self::DROPIN_XSPEED === self::dropin_owner() ) {
	8400	+ // Put WP_CACHE back, and say so if we could not. Reporting a
	8401	+ // hardcoded `enabled: true` here claimed a working cache on a
	8402	+ // site whose constant we had just failed to restore.
	8403	+ // Put WP_CACHE back, then read the outcome off disk rather than
	8404	+ // trusting the write's return value — a write can report failure
	8405	+ // for a value that was already correct, and the question the
	8406	+ // caller needs answered is whether the cache serves.
	8407	+ self::set_wp_cache_constant( true );
	8408	+ return self::blocked_toggle_state(
	8409	+ self::page_cache_operational()
	8410	+ ? __( 'xSpeed could not remove its page-cache drop-in. The cache remains enabled.', 'xspeed' )
	8411	+ : __( 'xSpeed could not remove its page-cache drop-in, and could not put WP_CACHE back. The cache is not serving; check wp-config.php before changing the page cache again.', 'xspeed' )
	8412	+ );
	8413	+ }
1064	8414	self::remove_rewrite();
	8415	+ /*
	8416	+ * The .htaccess block serves cached HTML straight off disk without
	8417	+ * ever reaching PHP, so a block we failed to remove keeps answering
	8418	+ * requests from a cache the user just turned off — and nothing else
	8419	+ * in this method can stop it. remove_rewrite() also returns false
	8420	+ * when there is no .htaccess to clean, which is the ordinary case,
	8421	+ * so ask the file rather than trust the return value.
	8422	+ */
	8423	+ if ( self::rewrite_installed() ) {
	8424	+ if ( $not_ours ) {
	8425	+ // Nothing to roll back — under a foreign drop-in this method
	8426	+ // removed no drop-in and wrote no constant, and it could not
	8427	+ // put either back if it wanted to. Say what is actually left.
	8428	+ return self::blocked_toggle_state( __( 'xSpeed could not remove its rewrite rules from .htaccess, which would keep serving cached pages. Remove the xSpeed block from .htaccess by hand before turning the page cache off.', 'xspeed' ) );
	8429	+ }
	8430	+ /*
	8431	+ * Roll the disable back. Both calls can fail — a filesystem that
	8432	+ * would not let us remove the block may not let us write the
	8433	+ * drop-in either — and discarding their results reported an
	8434	+ * enabled cache over a site left with no drop-in and no
	8435	+ * constant. Fall through to the default state so the artifact
	8436	+ * fields are read from disk rather than asserted.
	8437	+ */
	8438	+ self::install_dropin();
	8439	+ self::set_wp_cache_constant( true );
	8440	+ // Both of those can fail — a filesystem that would not let us
	8441	+ // remove the block may not let us write the drop-in either — so
	8442	+ // the message follows what is on disk afterwards, not what the
	8443	+ // calls returned.
	8444	+ return self::blocked_toggle_state(
	8445	+ self::page_cache_operational()
	8446	+ ? __( 'xSpeed could not remove its rewrite rules from .htaccess, which would keep serving cached pages. The cache remains enabled.', 'xspeed' )
	8447	+ : __( 'xSpeed could not remove its rewrite rules from .htaccess, and could not restore the drop-in it had just removed. The cache is not serving, and the site may still return stale cached pages until the xSpeed block is removed from .htaccess by hand.', 'xspeed' )
	8448	+ );
	8449	+ }
1065	8450	// Drop the device-bucket marker too — with the drop-in gone there's
1066	8451	// nothing left to read it, and leaving it behind would dirty a fresh
1067	8452	// re-enable (and leaks across test runs).
1068	8453	self::sync_mobile_flag( false );
	8454	+ Settings::update( array( 'cache_enabled' => false ) );
	8455	+ if ( ! empty( Settings::get()['cache_enabled'] ) ) {
	8456	+ if ( $not_ours ) {
	8457	+ // Same as above: there is nothing of ours on disk to restore.
	8458	+ return self::blocked_toggle_state( __( 'xSpeed could not save the disabled state.', 'xspeed' ) );
	8459	+ }
	8460	+ self::install_dropin();
	8461	+ self::set_wp_cache_constant( true );
	8462	+ return self::blocked_toggle_state( __( 'xSpeed could not save the disabled state. The page cache was restored.', 'xspeed' ) );
	8463	+ }
1069	8464
	8465	+ // A WP_CACHE we could not remove because wp-config.php is read-only
	8466	+ // is left behind deliberately (see above) — say so rather than
	8467	+ // reporting a constant that is still in the file as gone.
	8468	+ $constant_left = 'true' === self::wp_cache_define_state();
	8469	+ /*
	8470	+ * Say why the constant is still there, because there are now three
	8471	+ * different reasons and they call for different advice. Keyed off the
	8472	+ * same facts $leave_it was, so the log cannot drift from the decision
	8473	+ * it is describing — it did, briefly, and reported a wp-config.php as
	8474	+ * unwritable when the real reason was that we could not prove the
	8475	+ * line was ours.
	8476	+ */
	8477	+ if ( self::DROPIN_UNREADABLE === $owner ) {
	8478	+ $log_message = 'Cache disabled. advanced-cache.php could not be read, so it and the WP_CACHE setting were left untouched.';
	8479	+ } elseif ( $not_ours ) {
	8480	+ $log_message = 'Cache disabled. Another plugin owns advanced-cache.php, so its drop-in and its WP_CACHE setting were left untouched.';
	8481	+ } elseif ( ! $constant_left ) {
	8482	+ $log_message = 'Cache disabled. Drop-in removed.';
	8483	+ } elseif ( ! self::wp_cache_define_is_ours_to_remove( $owner ) ) {
	8484	+ $log_message = 'Cache disabled. WP_CACHE was left in place — it carries no proof xSpeed wrote it, and it does nothing without a drop-in.';
	8485	+ } elseif ( ! self::can_write_wp_config() ) {
	8486	+ $log_message = 'Cache disabled. Drop-in removed; wp-config.php not writable, so WP_CACHE was left in place (harmless without the drop-in).';
	8487	+ } else {
	8488	+ $log_message = 'Cache disabled. Drop-in removed; WP_CACHE was left in place (harmless without the drop-in).';
	8489	+ }
1070	8490	Activity_Log::record(
1071	8491	'cache_disabled_event',
1072		- 'Cache disabled. Drop-in removed.',
1073		- Activity_Log::INFO
	8492	+ $log_message,
	8493	+ $constant_left ? Activity_Log::WARN : Activity_Log::INFO
1074	8494	);
1075	8495
1076	8496	return array(
1077	8497	'enabled' => false,
	8498	+ 'blocked' => false,
	8499	+ 'blocked_reason' => null,
1078	8500	'dropin_installed' => false,
1079		- 'wp_cache_constant' => false,
	8501	+ 'wp_cache_constant' => $constant_left,
1080	8502	'rewrite_installed' => false,
1081	8503	'wp_config_writable' => self::wp_config_writable(),
1082	8504	'manual_snippet' => null,
1083	8505	'nginx_snippet' => self::nginx_snippet(),
		@@ -1084,9 +8506,134 @@
1084	8506	'nginx_server_block' => self::full_nginx_server_block(),
1085	8507	);
1086	8508	}
1087	8509
	8510	+ /** Acquire the local lock that serializes page-cache ownership changes. */
	8511	+ private static function page_cache_lock() {
	8512	+ $path = WP_CONTENT_DIR . '/.xspeed-page-cache.lock';
	8513	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen,WordPress.PHP.NoSilencedErrors.Discouraged -- flock requires a local handle; failure is a safe blocked result.
	8514	+ $lock = @fopen( $path, 'c+' );
	8515	+ if ( ! is_resource( $lock ) || ! flock( $lock, LOCK_EX ) ) {
	8516	+ return false;
	8517	+ }
	8518	+ return $lock;
	8519	+ }
	8520	+
1088	8521	/**
	8522	+ * Build the stable response shape for a refused transaction.
	8523	+ *
	8524	+ * The artifact fields report what is ON DISK, not zeros. A refusal means
	8525	+ * xSpeed changed nothing — on a site already running our cache that is
	8526	+ * exactly the state where the drop-in and WP_CACHE are both still in
	8527	+ * place and still serving hits. Hardcoding false told the dashboard the
	8528	+ * cache had been dismantled every time a refusal was returned.
	8529	+ */
	8530	+ private static function blocked_toggle_state( string $reason ): array {
	8531	+ /*
	8532	+ * `enabled` answers ONE question: is the page cache operational right
	8533	+ * now. Not what was asked for, and not what the option says.
	8534	+ *
	8535	+ * WordPress loads advanced-cache.php only when WP_CACHE is truthy, so
	8536	+ * those two files together are the whole answer, and reading them is
	8537	+ * the only source that cannot go stale. Both of the alternatives were
	8538	+ * tried here and both produced wrong answers on real paths: a
	8539	+ * hardcoded false told a caller the cache had gone away on a site
	8540	+ * still serving hits, and the persisted setting told a caller the
	8541	+ * cache was healthy after a rollback had just removed the artifacts
	8542	+ * — the option is not written until the end of the transaction, so
	8543	+ * mid-transaction it is stale by construction.
	8544	+ *
	8545	+ * Deliberately not a parameter. Every branch that got to choose its
	8546	+ * own answer eventually chose wrong.
	8547	+ */
	8548	+ return array(
	8549	+ 'enabled' => self::page_cache_operational(),
	8550	+ 'blocked' => true,
	8551	+ 'blocked_reason' => $reason,
	8552	+ 'dropin_installed' => self::DROPIN_XSPEED === self::dropin_owner(),
	8553	+ 'wp_cache_constant' => 'true' === self::wp_cache_define_state(),
	8554	+ 'rewrite_installed' => self::rewrite_installed(),
	8555	+ 'wp_config_writable' => self::wp_config_writable(),
	8556	+ 'manual_snippet' => null,
	8557	+ 'nginx_snippet' => self::nginx_snippet(),
	8558	+ 'nginx_server_block' => self::full_nginx_server_block(),
	8559	+ );
	8560	+ }
	8561	+
	8562	+ /**
	8563	+ * The wp-config.php line a user must paste, or null when none is needed.
	8564	+ *
	8565	+ * Non-null only where the drop-in is ours and WP_CACHE is not set to true
	8566	+ * in a file we can write — the read-only managed host. Everywhere else the
	8567	+ * constant is ours to manage and there is nothing to ask for.
	8568	+ */
	8569	+ public static function manual_wp_cache_snippet(): ?string {
	8570	+ if ( self::DROPIN_XSPEED !== self::dropin_owner() ) {
	8571	+ return null;
	8572	+ }
	8573	+ if ( 'true' === self::wp_cache_define_state() ) {
	8574	+ return null;
	8575	+ }
	8576	+ return self::wp_config_writable() ? null : "define( 'WP_CACHE', true );";
	8577	+ }
	8578	+
	8579	+ /**
	8580	+ * Is the page cache serving right now?
	8581	+ *
	8582	+ * Two things decide it, and `WP_CACHE` is not one of them.
	8583	+ *
	8584	+ * xSpeed serves a cached page from `template_redirect` whenever the
	8585	+ * setting is on — see the `HIT (php)` mark on that path, which exists
	8586	+ * precisely for "the drop-in isn't loaded". `advanced-cache.php` and the
	8587	+ * `WP_CACHE` constant that loads it are the FAST path: they answer before
	8588	+ * WordPress boots, which is worth a lot of milliseconds and nothing at
	8589	+ * all to the question of whether pages are being served from cache.
	8590	+ *
	8591	+ * Conflating the two reported a dead cache over a live one. On a managed
	8592	+ * host with an unwritable wp-config.php — the exact case the manual
	8593	+ * snippet exists for — one card said "Your cache works on every request",
	8594	+ * "On, but not serving", "nothing will be cached until you add this line"
	8595	+ * and "hit ratio 67%", all at once, and told the user to edit a file they
	8596	+ * have no permission to write. The released 1.2.1 reported that site as
	8597	+ * active, correctly.
	8598	+ *
	8599	+ * So: the setting, and whether anyone else holds the drop-in. A foreign
	8600	+ * drop-in answers before WordPress loads us, so ours never runs and we
	8601	+ * genuinely are not serving. An unreadable one we must assume the same of.
	8602	+ * Everything else — our drop-in, or none at all — serves.
	8603	+ *
	8604	+ * Public because it is part of the host-plugin contract — see Host. A
	8605	+ * plugin that installed xSpeed needs to be able to say whether the cache
	8606	+ * it asked for is actually serving, and no combination of settings reads
	8607	+ * answers that.
	8608	+ */
	8609	+ public static function page_cache_operational(): bool {
	8610	+ $settings = Settings::get();
	8611	+ if ( empty( $settings['cache_enabled'] ) ) {
	8612	+ return false;
	8613	+ }
	8614	+ $owner = self::dropin_owner();
	8615	+ return self::DROPIN_FOREIGN !== $owner && self::DROPIN_UNREADABLE !== $owner;
	8616	+ }
	8617	+
	8618	+ /** Restore exact snapshots only while disk still matches our own write. */
	8619	+ private static function rollback_page_cache_artifacts( string $dropin_path, ?string $dropin_before, ?string $dropin_written, string $config_path, ?string $config_before, ?string $config_written ): void {
	8620	+ // Roll back only files that still carry xSpeed's just-written state.
	8621	+ if ( null !== $dropin_written && hash_equals( $dropin_written, (string) self::read_file( $dropin_path ) ) ) {
	8622	+ if ( null === $dropin_before ) {
	8623	+ wp_delete_file( $dropin_path );
	8624	+ } else {
	8625	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- Exact compare-and-swap rollback under the scoped lock.
	8626	+ file_put_contents( $dropin_path, $dropin_before );
	8627	+ }
	8628	+ }
	8629	+ if ( '' !== $config_path && null !== $config_before && null !== $config_written && hash_equals( $config_written, (string) self::read_file( $config_path ) ) && self::wp_cache_receipt_matches_source( $config_written ) ) {
	8630	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- Exact compare-and-swap rollback under the scoped lock.
	8631	+ file_put_contents( $config_path, $config_before );
	8632	+ }
	8633	+ }
	8634	+
	8635	+ /**
1089	8636	* Check wp-config.php writability via WP_Filesystem. Plugin Check flags
1090	8637	* direct is_writable() under WordPress.WP.AlternativeFunctions.
1091	8638	*/
1092	8639	private static function wp_config_writable() {
		@@ -1123,10 +8670,11 @@
1123	8670	* they don't share a user at all. A default-umask 0644 file is then
1124	8671	* unwritable by nginx, the access_log write silently fails, and the
1125	8672	* dashboard shows a 0% hit ratio even though static HITs are serving.
1126	8673	* So we widen the dir to 0777 and the file to 0666 — group/other write —
1127		- * so whatever uid nginx runs as can append. (The file holds only HIT
1128		- * request lines, no secrets.)
	8674	+ * so whatever uid nginx runs as can append. The file holds HIT request
	8675	+ * lines and must be protected like an access log: paths and queries can
	8676	+ * contain sensitive values.
1129	8677	*/
1130	8678	/**
1131	8679	* Directory holding the nginx hit log. Lives under uploads/, NOT the
1132	8680	* cache dir — uninstall.php and a cache purge both delete the cache
		@@ -1140,11 +8688,22 @@
1140	8688	* Falls back to the cache dir only if uploads is somehow unavailable.
1141	8689	*/
1142	8690	public static function hits_log_dir(): string {
1143	8691	if ( function_exists( 'wp_upload_dir' ) ) {
	8692	+ // One drop-in serves the whole network, so its hit log has one
	8693	+ // home: the main site's uploads. Resolved per blog, the path
	8694	+ // baked into the drop-in changed with whichever blog's admin
	8695	+ // last ran auto_heal(), and each rewrite read as a page-cache
	8696	+ // change and purged the site and the edge (QA, 2026-09-23).
	8697	+ // A subsite's uploads are `<main uploads>/sites/<id>`, so the
	8698	+ // suffix comes off rather than switching blogs to ask.
1144	8699	$uploads = wp_upload_dir( null, false );
1145	8700	if ( is_array( $uploads ) && empty( $uploads['error'] ) && ! empty( $uploads['basedir'] ) ) {
1146		- return rtrim( (string) $uploads['basedir'], '/' ) . '/xspeed';
	8701	+ $base = rtrim( (string) $uploads['basedir'], '/' );
	8702	+ if ( function_exists( 'is_multisite' ) && is_multisite() ) {
	8703	+ $base = (string) preg_replace( '#/sites/\d+$#', '', $base );
	8704	+ }
	8705	+ return $base . '/xspeed';
1147	8706	}
1148	8707	}
1149	8708	return XSPEED_CACHE_DIR;
1150	8709	}
		@@ -1169,12 +8728,218 @@
1169	8728	* and the fast pre-WP path was silently dead.
1170	8729	*
1171	8730	* @param bool|null $enabled Force a state; null reads the current setting.
1172	8731	*/
	8732	+ /**
	8733	+ * Write the subdirectory-multisite path list the drop-in needs to work
	8734	+ * out which blog a request belongs to.
	8735	+ *
	8736	+ * The drop-in runs before WordPress, so it cannot call is_multisite()
	8737	+ * or get_blog_details(). It can only see REQUEST_URI — so we persist the
	8738	+ * network's blog paths (one per line, longest first) next to the cache
	8739	+ * files, exactly as sync_mobile_flag() persists the device flag. The
	8740	+ * drop-in prefix-matches the URI against that list to pick the same
	8741	+ * bucket Cache::current_host_dir() picks. (#6)
	8742	+ *
	8743	+ * No file is written for a single site or a subdomain network — there
	8744	+ * the host alone identifies the blog and the bucket carries no prefix.
	8745	+ */
	8746	+ public static function sync_site_paths(): void {
	8747	+ $file = XSPEED_CACHE_DIR . '/.site-paths';
	8748	+
	8749	+ $needed = function_exists( 'is_multisite' ) && is_multisite()
	8750	+ && ( ! function_exists( 'is_subdomain_install' ) || ! is_subdomain_install() );
	8751	+
	8752	+ if ( ! $needed ) {
	8753	+ if ( file_exists( $file ) ) {
	8754	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
	8755	+ @unlink( $file );
	8756	+ }
	8757	+ return;
	8758	+ }
	8759	+
	8760	+ if ( ! function_exists( 'get_sites' ) ) {
	8761	+ return;
	8762	+ }
	8763	+
	8764	+ $paths = array();
	8765	+ foreach ( get_sites( array( 'number' => 0 ) ) as $site ) {
	8766	+ $prefix = self::path_prefix_segment( (string) $site->path );
	8767	+ if ( '' !== $prefix ) {
	8768	+ // Store the raw path so the drop-in can prefix-match a URI,
	8769	+ // alongside the segment it maps to.
	8770	+ $paths[ trim( (string) $site->path, '/' ) ] = $prefix;
	8771	+ }
	8772	+ }
	8773	+
	8774	+ if ( empty( $paths ) ) {
	8775	+ if ( file_exists( $file ) ) {
	8776	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- see above.
	8777	+ @unlink( $file );
	8778	+ }
	8779	+ return;
	8780	+ }
	8781	+
	8782	+ // Longest path first so /a/b wins over /a.
	8783	+ uksort(
	8784	+ $paths,
	8785	+ static function ( $x, $y ) {
	8786	+ return strlen( (string) $y ) <=> strlen( (string) $x );
	8787	+ }
	8788	+ );
	8789	+
	8790	+ $lines = array();
	8791	+ foreach ( $paths as $raw => $segment ) {
	8792	+ $lines[] = $raw . '|' . $segment;
	8793	+ }
	8794	+
	8795	+ if ( ! is_dir( XSPEED_CACHE_DIR ) && ! wp_mkdir_p( XSPEED_CACHE_DIR ) ) {
	8796	+ return;
	8797	+ }
	8798	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- read by the pre-WP drop-in; WP_Filesystem needs admin credentials unavailable here.
	8799	+ file_put_contents( $file, implode( "\n", $lines ), LOCK_EX );
	8800	+ }
	8801	+
	8802	+ /**
	8803	+ * Compile `ignored_query_params` into a regex the DROP-IN can use.
	8804	+ *
	8805	+ * Tracking traffic was cached but never served fast. should_cache()
	8806	+ * learned to allow `?utm_source=…` through and cache_key() strips the
	8807	+ * query, so `/post` and `/post?utm_source=x` share one entry — but the
	8808	+ * drop-in still bailed on ANY query string, so every visitor from an
	8809	+ * email or ad campaign paid a full WordPress boot to be handed a file
	8810	+ * that was already on disk. On a marketing site that is most of the
	8811	+ * paid traffic taking the slowest path. (#13)
	8812	+ *
	8813	+ * The drop-in runs before WordPress, so it cannot read the option or
	8814	+ * call Glob_Matcher. It gets a precompiled alternation instead, written
	8815	+ * next to the cache files exactly as sync_mobile_flag() writes the
	8816	+ * device flag. Regenerated whenever cache settings are saved.
	8817	+ *
	8818	+ * Only the KEYS matter: a param whose name is on the list contributes
	8819	+ * nothing to the response, so the entry keyed without it is correct.
	8820	+ * Anything not on the list means the drop-in must stand down and let
	8821	+ * PHP decide — the file is deleted rather than left stale when the
	8822	+ * list is empty, so a missing sidecar always fails safe.
	8823	+ */
	8824	+ public static function sync_query_allowlist(): void {
	8825	+ $file = XSPEED_CACHE_DIR . '/.ignored-query-params';
	8826	+
	8827	+ /*
	8828	+ * Stored read, not Settings_Manager::get() — this runs from boot(),
	8829	+ * before translation is legal (see stored_cache_opts()).
	8830	+ *
	8831	+ * A raw read applies no schema defaults, and this field's default is a
	8832	+ * long tracking-parameter list, NOT empty. Falling back to array()
	8833	+ * would strip that whole allow-list from the drop-in on any install
	8834	+ * that has never saved the Cache panel. So fall back to the schema's
	8835	+ * own default, read from the module without building its labels.
	8836	+ */
	8837	+ $opts = self::stored_cache_opts();
	8838	+ $ignored = is_array( $opts['ignored_query_params'] ?? null )
	8839	+ ? $opts['ignored_query_params']
	8840	+ : \XSpeed\Modules\Cache\CacheModule::default_ignored_query_params();
	8841	+
	8842	+ $parts = array();
	8843	+ foreach ( $ignored as $pattern ) {
	8844	+ $pattern = trim( (string) $pattern );
	8845	+ if ( '' === $pattern ) {
	8846	+ continue;
	8847	+ }
	8848	+ if ( '~' === $pattern[0] ) {
	8849	+ // Raw regex, PHP-side dialect. Keep it — unlike a server
	8850	+ // config, the drop-in runs the same PCRE engine, so the
	8851	+ // pattern behaves identically. Anchored below with the rest.
	8852	+ $body = substr( $pattern, 1 );
	8853	+ if ( '' !== $body && false !== @preg_match( '#^(?:' . $body . ')$#', '' ) ) { // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- a malformed user pattern must be dropped, not fatal.
	8854	+ $parts[] = $body;
	8855	+ }
	8856	+ continue;
	8857	+ }
	8858	+ // Glob semantics, same as Glob_Matcher: * is any run, ? is one.
	8859	+ $esc = preg_quote( $pattern, '#' );
	8860	+ $esc = str_replace( array( '\*', '\?' ), array( '.*', '.' ), $esc );
	8861	+ $parts[] = $esc;
	8862	+ }
	8863	+
	8864	+ if ( empty( $parts ) ) {
	8865	+ if ( file_exists( $file ) ) {
	8866	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
	8867	+ @unlink( $file );
	8868	+ }
	8869	+ return;
	8870	+ }
	8871	+
	8872	+ if ( ! is_dir( XSPEED_CACHE_DIR ) && ! wp_mkdir_p( XSPEED_CACHE_DIR ) ) {
	8873	+ return;
	8874	+ }
	8875	+
	8876	+ // The drop-in anchors this as `^…$`, so the lookahead refuses the
	8877	+ // never-ignored names whole, whatever entry would have matched them.
	8878	+ $never = implode( '|', array_map( static fn ( $p ) => preg_quote( $p, '#' ), self::NEVER_IGNORED_QUERY_PARAMS ) );
	8879	+ $payload = '(?!(?:' . $never . ')$)(?:' . implode( '|', array_unique( $parts ) ) . ')';
	8880	+
	8881	+ // Only write when the value actually changed. This runs from
	8882	+ // reconcile_mobile_separate() on CacheModule::boot(), so an
	8883	+ // unconditional write cost a file write and an exclusive lock on every
	8884	+ // request that boots WordPress — every MISS, every BYPASS, every admin
	8885	+ // screen, every REST call. sync_mobile_flag() below is the model: it
	8886	+ // touches the marker only when the setting flips.
	8887	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents, WordPress.PHP.NoSilencedErrors.Discouraged -- our own sidecar; an unreadable file falls through to the write below.
	8888	+ if ( is_readable( $file ) && (string) @file_get_contents( $file ) === $payload ) {
	8889	+ return;
	8890	+ }
	8891	+
	8892	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- read by the pre-WP drop-in; WP_Filesystem needs admin credentials unavailable here.
	8893	+ file_put_contents( $file, $payload, LOCK_EX );
	8894	+ }
	8895	+
	8896	+ /**
	8897	+ * CacheModule's STORED settings, read straight from the option.
	8898	+ *
	8899	+ * `Settings_Manager::get( 'cache' )` builds CacheModule's settings schema,
	8900	+ * whose labels are declared through `__()`. The reconcile chain below runs
	8901	+ * from `CacheModule::boot()` on `plugins_loaded` — before
	8902	+ * `after_setup_theme`, the point WordPress 6.7+ treats as safe to
	8903	+ * translate — so going through the schema there fires
	8904	+ * `_load_textdomain_just_in_time` on every request AND resolves the labels
	8905	+ * against a domain that is not loaded yet.
	8906	+ *
	8907	+ * The callers here need stored values, not schema metadata, so a raw read
	8908	+ * is equivalent. It applies NO defaults or coercion: read each key with a
	8909	+ * fallback matching the schema's own default.
	8910	+ *
	8911	+ * @return array<string,mixed>
	8912	+ */
	8913	+ private static function stored_cache_opts(): array {
	8914	+ $stored = get_option( Settings_Manager::OPTION_PREFIX . 'cache', array() );
	8915	+ return is_array( $stored ) ? $stored : array();
	8916	+ }
	8917	+
	8918	+ /**
	8919	+ * Strict truthiness for the LiteSpeed Static Fast Path opt-in.
	8920	+ *
	8921	+ * On non-LiteSpeed servers the key is out of the schema and carried by
	8922	+ * preserved_keys(), so a REST/MCP write lands VERBATIM — QA on #513
	8923	+ * stored the string "false" on Apache and the fast path installed
	8924	+ * itself the moment the site moved to LiteSpeed, because
	8925	+ * empty("false") is false. Only an explicit, unambiguous "yes" may
	8926	+ * enable a path that trades away hit tagging; any other value —
	8927	+ * "false", "no", arbitrary junk — stays OFF, which is the default the
	8928	+ * user never left.
	8929	+ */
	8930	+ private static function litespeed_optin_enabled( $value ): bool {
	8931	+ if ( true === $value || 1 === $value ) {
	8932	+ return true;
	8933	+ }
	8934	+ return is_string( $value )
	8935	+ && in_array( strtolower( trim( $value ) ), array( '1', 'true', 'on', 'yes' ), true );
	8936	+ }
	8937	+
1173	8938	public static function sync_mobile_flag( $enabled = null ): void {
1174	8939	if ( null === $enabled ) {
1175		- $opts = Settings_Manager::get( 'cache' );
1176		- $enabled = ! empty( $opts['mobile_separate'] );
	8940	+ $stored = self::stored_cache_opts();
	8941	+ $enabled = ! empty( $stored['mobile_separate'] );
1177	8942	}
1178	8943	$dir = XSPEED_CACHE_DIR;
1179	8944	$flag = $dir . '/.mobile-separate';
1180	8945	if ( $enabled ) {
		@@ -1187,9 +8952,9 @@
1187	8952	}
1188	8953	return;
1189	8954	}
1190	8955	if ( file_exists( $flag ) ) {
1191		- // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
	8956	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
1192	8957	@unlink( $flag );
1193	8958	}
1194	8959	}
1195	8960
		@@ -1217,9 +8982,9 @@
1217	8982	}
1218	8983	return;
1219	8984	}
1220	8985	if ( file_exists( $flag ) ) {
1221		- // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
	8986	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.unlink_unlink, WordPress.PHP.NoSilencedErrors.Discouraged -- plain marker removal; non-fatal.
1222	8987	@unlink( $flag );
1223	8988	}
1224	8989	}
1225	8990
		@@ -1240,8 +9005,16 @@
1240	9005	* reconcile, and toggle() handles install/teardown itself.
1241	9006	*/
1242	9007	public static function reconcile_mobile_separate(): void {
1243	9008	self::sync_mobile_flag();
	9009	+ if ( defined( 'XSPEED_CACHE_DIR' ) ) {
	9010	+ // Keep the drop-in's view of the network's blog paths current — a
	9011	+ // site added or removed changes which bucket its URLs belong to. (#6)
	9012	+ self::sync_site_paths();
	9013	+ // Keep the drop-in's copy of the query allow-list current — a param
	9014	+ // added in settings must reach the fast path too. (#13)
	9015	+ self::sync_query_allowlist();
	9016	+ }
1244	9017
1245	9018	// The rewrite/static reconciliation below needs the plugin's path
1246	9019	// constants. They're absent in early-boot / unit-test contexts where
1247	9020	// only the drop-in flag matters — bail to the flag-only behavior then.
		@@ -1257,8 +9030,31 @@
1257	9030
1258	9031	$rewrite_present = self::rewrite_installed();
1259	9032	$rewrite_wanted = self::static_rewrite_allowed();
1260	9033
	9034	+ // Did the thing that actually invalidates cache KEYS change?
	9035	+ // mobile_separate buckets entries as |d / |m, so flipping it makes
	9036	+ // stored entries mis-bucketed and they must go. A rewrite-state
	9037	+ // mismatch from anything else (e.g. mod_headers detection, a hand-
	9038	+ // edited .htaccess) changes no key at all — the same files are still
	9039	+ // valid, they're just served by PHP instead of by the web server.
	9040	+ // Purging there is what let one WP-CLI call wipe the whole cache on
	9041	+ // every bootstrap. (#138)
	9042	+ //
	9043	+ // Read the setting from the SAME place static_rewrite_allowed() and
	9044	+ // sync_mobile_flag() do — the cache module's settings, not the
	9045	+ // top-level xspeed_options — or this marker would track a key that
	9046	+ // never changes and a real flip would go unnoticed.
	9047	+ // Stored read — this runs from boot(); see stored_cache_opts().
	9048	+ $cache_opts = self::stored_cache_opts();
	9049	+ $mobile_now = ! empty( $cache_opts['mobile_separate'] );
	9050	+ $mobile_last = get_option( 'xspeed_last_mobile_separate', null );
	9051	+ $mobile_flipped = ( null !== $mobile_last && (bool) (int) $mobile_last !== $mobile_now );
	9052	+
	9053	+ if ( (string) (int) $mobile_now !== (string) $mobile_last ) {
	9054	+ update_option( 'xspeed_last_mobile_separate', $mobile_now ? '1' : '0', false );
	9055	+ }
	9056	+
1261	9057	if ( $rewrite_present === $rewrite_wanted ) {
1262	9058	// Already consistent — nothing flipped, leave caches intact so a
1263	9059	// plain settings save (e.g. expiry change) doesn't blow the cache.
1264	9060	return;
		@@ -1263,17 +9059,19 @@
1263	9059	// plain settings save (e.g. expiry change) doesn't blow the cache.
1264	9060	return;
1265	9061	}
1266	9062
1267		- // The setting flipped. Bring the rewrite into line and purge the
1268		- // now-misbucketed cache so the next request re-primes under the new
1269		- // device scheme.
	9063	+ // Bring the rewrite into line with what this server actually supports.
1270	9064	if ( $rewrite_wanted ) {
1271	9065	self::install_rewrite();
1272	9066	} else {
1273	9067	self::remove_rewrite();
1274	9068	}
1275		- self::purge_all( 'mobile_separate changed' );
	9069	+
	9070	+ // Only discard cache contents when the device bucketing changed.
	9071	+ if ( $mobile_flipped ) {
	9072	+ self::purge_all( 'mobile_separate changed' );
	9073	+ }
1276	9074	}
1277	9075
1278	9076	/**
1279	9077	* Whether the server-level static-rewrite fast path may be used.
		@@ -1297,10 +9095,12 @@
1297	9095	* `.htaccess` equivalent of nginx's per-location `access_log` to record
1298	9096	* the hit. The result was a cache that worked but was invisible: no HIT
1299	9097	* header and a hit-ratio frozen near 0%. Every OTHER server gives the
1300	9098	* user a visible HIT header + a counted hit (nginx via add_header +
1301		- * access_log in its snippet; Apache via .htaccess mod_headers, which it
1302		- * honors). To keep LiteSpeed CONSISTENT with the rest, we route its hits
	9099	+ * access_log in its snippet; Apache via the `<IfModule mod_headers.c>`
	9100	+ * block in rewrite_block_lines(), WHEN that module is loaded — when it is
	9101	+ * not, Apache takes this same drop-in fallback). To keep LiteSpeed
	9102	+ * CONSISTENT with the rest, we route its hits
1303	9103	* through the PHP drop-in instead — the drop-in emits
1304	9104	* `X-XSpeed-Cache: HIT (php)` and calls Hit_Counter inline, exactly the
1305	9105	* observable behavior the other servers get. The cost is the drop-in's
1306	9106	* ~30ms TTFB vs the static path's ~10ms, paid only on LiteSpeed; in
		@@ -1308,34 +9108,501 @@
1308	9108	* the truth there. (Apache keeps the static fast path — it honors the
1309	9109	* header.) See maybe_emit_lscache_headers() for the paired LSCache
1310	9110	* stand-down that stops LiteSpeed's own module from shadowing the
1311	9111	* drop-in.
	9112	+ *
	9113	+ * Opt-in (#509): `litespeed_static_rewrite` re-enables the fast path on
	9114	+ * LiteSpeed for users who value raw TTFB over hit accounting. The trade
	9115	+ * is stated in the setting's copy: statically served hits carry no
	9116	+ * X-XSpeed-Cache header and are not counted (LiteSpeed logs the
	9117	+ * original request line, so even the access-log scan cannot see
	9118	+ * them — see Hit_Counter::collect_server_log_hits()). The drop-in
	9119	+ * default above stays — nobody is surprised into an unverifiable cache.
1312	9120	*/
1313	9121	public static function static_rewrite_allowed(): bool {
1314		- // LiteSpeed: drop-in serves hits (visible + counted) — see docblock.
	9122	+ // Stored read — reached from boot(); see stored_cache_opts().
	9123	+ $opts = self::stored_cache_opts();
	9124	+ // LiteSpeed: drop-in serves hits (visible + counted) unless the user
	9125	+ // explicitly opted into the static fast path — see docblock.
	9126	+ if ( Server::LITESPEED === Server::type()
	9127	+ && ! self::litespeed_optin_enabled( $opts['litespeed_static_rewrite'] ?? false ) ) {
	9128	+ return false;
	9129	+ }
	9130	+ // Apache without mod_headers is in EXACTLY the position LiteSpeed
	9131	+ // is in above: it can run the RewriteRule and serve the static
	9132	+ // file, but it cannot stamp `X-XSpeed-Cache` on the response, so
	9133	+ // the hit is invisible to the user and uncountable by
	9134	+ // Hit_Counter. The docblock above used to assert Apache "honors
	9135	+ // mod_headers" and left it on the fast path unconditionally —
	9136	+ // true only when the module is actually loaded. Fall back to the
	9137	+ // drop-in when it isn't, trading ~10ms of TTFB for a hit that
	9138	+ // shows up in the header and the ratio. (Field report: hit ratio
	9139	+ // pinned at 0% on a working Apache cache.)
	9140	+ if ( Server::APACHE === Server::type() && ! Server::apache_has_mod_headers() ) {
	9141	+ return false;
	9142	+ }
	9143	+ return empty( $opts['mobile_separate'] );
	9144	+ }
	9145	+
	9146	+ /**
	9147	+ * Why the device-blind static rewrite is NOT installed, when it isn't.
	9148	+ * Returns 'mobile_separate' when Separate Mobile Cache is the blocker
	9149	+ * (the static file is one-per-URL, so it can't coexist with per-device
	9150	+ * buckets), 'no_mod_headers' when Apache can't stamp the HIT header,
	9151	+ * '' otherwise. Lets the dashboard explain the slow path instead of
	9152	+ * silently falling back to PHP serving. (FBS-83145)
	9153	+ *
	9154	+ * Every refusal in static_rewrite_allowed() that is NOT self-explanatory
	9155	+ * must have a branch here. Otherwise the Health card falls through to
	9156	+ * "Block missing — toggle Enable Cache off and on to reinstall it",
	9157	+ * advice that cannot work: the same condition that suppressed the write
	9158	+ * suppresses the reinstall, and auto_heal() strips the block again on
	9159	+ * the next admin page load. (Field report: Apache host with mod_headers
	9160	+ * unloaded sat on the slow path with no way to find out why.)
	9161	+ */
	9162	+ /**
	9163	+ * Qualify a raw probe result with what we already KNOW about config.
	9164	+ *
	9165	+ * probe_static_rewrite() writes its own file under the static-cache tree
	9166	+ * and fetches that, which succeeds whenever the web server can serve a
	9167	+ * static file at all — including when static_rewrite_allowed() is false
	9168	+ * and no real page is on the static path. So `active: true` on its own is
	9169	+ * not evidence that pages are being served statically.
	9170	+ *
	9171	+ * The reachable case is nginx with Separate Mobile Cache on: the snippet
	9172	+ * lives in the server block and we cannot remove it, pages are
	9173	+ * deliberately routed to the PHP drop-in, but the probe file is still
	9174	+ * served directly.
	9175	+ *
	9176	+ * The Health panel learned this in 88b4b50; the CLI, REST and MCP paths
	9177	+ * did not, so they kept reporting "active" in exactly that configuration.
	9178	+ * Rather than repeat the reasoning at each call site, they now all come
	9179	+ * through here.
	9180	+ *
	9181	+ * Deliberately does NOT consult rewrite_installed(): on nginx the fast
	9182	+ * path is the pasted snippet and there is no .htaccess marker to find, so
	9183	+ * requiring one would report every correctly-configured nginx site as
	9184	+ * broken.
	9185	+ *
	9186	+ * Carries `rules` through as well. The dashboard bootstrap builds its own
	9187	+ * payload and so had it; every other caller — POST /cache/recheck-rewrite,
	9188	+ * `wp xspeed cache recheck-rewrite`, the recheck_rewrite_rules MCP tool —
	9189	+ * came through here and got four keys, so the one surface a user reaches
	9190	+ * AFTER pasting the block could not tell them whether the block took. An
	9191	+ * agent driving the same fix could not read it at all.
	9192	+ *
	9193	+ * @param array $probe Raw result from probe_static_rewrite().
	9194	+ * @return array{active:bool,inconclusive:bool,reason:string,block_reason:string,rules:array}
	9195	+ */
	9196	+ public static function qualify_rewrite_probe( array $probe ): array {
	9197	+ $active = (bool) ( $probe['active'] ?? false );
	9198	+ $inconclusive = (bool) ( $probe['inconclusive'] ?? false );
	9199	+ $reason = (string) ( $probe['reason'] ?? '' );
	9200	+ $block_reason = self::static_rewrite_block_reason();
	9201	+ $rules = self::rules_state( $probe );
	9202	+
	9203	+ // Same observed-refusal check Health makes. This is the shared path for
	9204	+ // `wp xspeed cache recheck-rewrite` and POST /cache/recheck-rewrite —
	9205	+ // and, because a CLI command is automatically an MCP tool, for the
	9206	+ // AI-facing surface too. Leaving it out would have fixed the dashboard
	9207	+ // while the CLI kept answering that the fast path was active. (#372)
	9208	+ if ( '' === $block_reason ) {
	9209	+ $skip = self::last_static_skip();
	9210	+ if ( ! empty( $skip['reason'] ) ) {
	9211	+ $block_reason = 'skipped_' . (string) $skip['reason'];
	9212	+ }
	9213	+ }
	9214	+
	9215	+ // With page caching off there is nothing to serve, so `active` can
	9216	+ // never be true here whatever the raw probe says. probe_static_rewrite()
	9217	+ // writes its OWN file under the static tree and fetches that, which
	9218	+ // succeeds whenever the server can serve a static file at all — and on
	9219	+ // nginx the snippet is server-level, so it keeps succeeding after the
	9220	+ // cache is switched off.
	9221	+ //
	9222	+ // block_reason() used to carry this meaning by accident: it returned
	9223	+ // 'mobile_separate' with caching off, and the refusal branch below
	9224	+ // forced active=false. Now that it correctly reports '' (nothing can
	9225	+ // block a fast path that isn't in use), this consumer has to state the
	9226	+ // condition itself — otherwise `wp xspeed cache recheck-rewrite` and
	9227	+ // POST /cache/recheck-rewrite claim "the web server is serving cache
	9228	+ // hits directly" on a site with no cache. That is a positive false
	9229	+ // claim rather than a nag, i.e. worse than the bug being fixed.
	9230	+ $cache_opts = Settings::get();
	9231	+ if ( empty( $cache_opts['cache_enabled'] ) ) {
	9232	+ return array(
	9233	+ 'active' => false,
	9234	+ 'inconclusive' => false,
	9235	+ 'reason' => 'Page caching is off, so there is no cache for the web server to serve.',
	9236	+ 'block_reason' => '',
	9237	+ 'rules' => $rules,
	9238	+ );
	9239	+ }
	9240	+
	9241	+ // A known refusal outranks the probe, and also outranks
	9242	+ // "inconclusive" — a blocked rewrite whose probe merely failed to
	9243	+ // complete is still definitely blocked.
	9244	+ if ( '' !== $block_reason ) {
	9245	+ $active = false;
	9246	+ $inconclusive = false;
	9247	+ $reason = self::block_reason_text( $block_reason );
	9248	+ }
	9249	+
	9250	+ return array(
	9251	+ 'active' => $active,
	9252	+ 'inconclusive' => $inconclusive,
	9253	+ 'reason' => $reason,
	9254	+ 'block_reason' => $block_reason,
	9255	+ 'rules' => $rules,
	9256	+ );
	9257	+ }
	9258	+
	9259	+ /**
	9260	+ * Human-readable explanation for a static_rewrite_block_reason() code.
	9261	+ *
	9262	+ * Each one has to say what to DO about it: "mobile_separate" alone tells
	9263	+ * a user nothing, and the whole point of surfacing a refusal instead of
	9264	+ * the probe verdict is that it is actionable.
	9265	+ */
	9266	+ public static function block_reason_text( string $code ): string {
	9267	+ switch ( $code ) {
	9268	+ case 'mobile_separate':
	9269	+ return 'Separate Mobile Cache is on, which disables the device-blind static rewrite. Cache hits are served by PHP instead. If your site serves the same HTML to every device, turn it off in Cache settings for much faster hits.';
	9270	+ case 'no_mod_headers':
	9271	+ return "Apache's mod_headers is not loaded, so the static rewrite cannot mark its responses as cache hits. Enable mod_headers, or leave hits on the PHP path.";
	9272	+ case 'litespeed_dropin':
	9273	+ return 'On LiteSpeed, cache hits are served by the PHP drop-in so every hit is tagged X-XSpeed-Cache and counted in the hit ratio — LiteSpeed\'s .htaccess engine cannot do either for statically served files. If raw TTFB matters more to you than hit accounting, turn on LiteSpeed Static Fast Path in Cache settings to serve hits straight from the web server.';
	9274	+ case 'skipped_nonce':
	9275	+ return 'The server config is correct, but pages are not reaching the static cache because they contain nonces, so hits are served by PHP instead. A static file is served with no PHP, so a nonce baked into one could never be refreshed and every anonymous form on the page would break once it expired — keeping these pages on PHP is deliberate. Nonces usually come from plugin widgets; disabling the ones the site does not use lets its pages be served statically again.';
	9276	+ default:
	9277	+ return sprintf( 'The static rewrite is disabled (%s).', $code );
	9278	+ }
	9279	+ }
	9280	+
	9281	+ public static function static_rewrite_block_reason(): string {
	9282	+ // Nothing can be blocking the fast path when there is no cache to
	9283	+ // serve from it. Without this the dashboard told users with page
	9284	+ // caching switched OFF that Separate Mobile Cache "is disabling
	9285	+ // faster static serving" — a fast path they were not using, about a
	9286	+ // cache that did not exist. Every caller of this is a user-facing
	9287	+ // explanation of why the rewrite is off, so "the cache is off" is
	9288	+ // the honest answer, and it is silence. (#108)
	9289	+ $opts = Settings::get();
	9290	+ if ( empty( $opts['cache_enabled'] ) ) {
	9291	+ return '';
	9292	+ }
1315	9293	if ( Server::LITESPEED === Server::type() ) {
	9294	+ // The opt-in is read RAW (stored_cache_opts), not through
	9295	+ // Settings_Manager::get(): the schema's bool coercion is a PHP
	9296	+ // cast, and (bool) "false" is true — so a junk string stored on
	9297	+ // another server (where the key bypasses the schema) would come
	9298	+ // back from the coercion layer as an ENABLE. Raw + the strict
	9299	+ // parse below is the same read static_rewrite_allowed() makes,
	9300	+ // so the two can't disagree either. (QA on #513)
	9301	+ $stored = self::stored_cache_opts();
	9302	+ // The intended default — but no longer silent: with the opt-in
	9303	+ // off, Health must be able to explain the PHP path and point at
	9304	+ // the toggle instead of falling through to "reinstall the block"
	9305	+ // advice that cannot work here. (#509)
	9306	+ if ( ! self::litespeed_optin_enabled( $stored['litespeed_static_rewrite'] ?? false ) ) {
	9307	+ return 'litespeed_dropin';
	9308	+ }
	9309	+ $cache_opts = Settings_Manager::get( 'cache' );
	9310	+ return ! empty( $cache_opts['mobile_separate'] ) ? 'mobile_separate' : '';
	9311	+ }
	9312	+ if ( Server::APACHE === Server::type() && ! Server::apache_has_mod_headers() ) {
	9313	+ return 'no_mod_headers';
	9314	+ }
	9315	+ $cache_opts = Settings_Manager::get( 'cache' );
	9316	+ return ! empty( $cache_opts['mobile_separate'] ) ? 'mobile_separate' : '';
	9317	+ }
	9318	+
	9319	+ /**
	9320	+ * Whether migration flagged Separate Mobile Cache for user review. Set by
	9321	+ * Migration::map_mobile_separate() when a source plugin (WP Rocket / WP
	9322	+ * Super Cache / LiteSpeed) had its "separate mobile cache" option on: we
	9323	+ * import it as OFF (to keep the device-blind static fast path) but record
	9324	+ * this flag so the dashboard can invite the user to turn it back on only
	9325	+ * if their site genuinely serves different HTML per device. (FBS-83145)
	9326	+ */
	9327	+ public static function mobile_separate_needs_review(): bool {
	9328	+ // Same reasoning as static_rewrite_block_reason(): the invitation is
	9329	+ // "turn this back on if your site needs it, to regain the fast path",
	9330	+ // which is meaningless with page caching off — there is no fast path
	9331	+ // to regain, and the equality probe behind the prompt would fetch
	9332	+ // pages that aren't being cached. Gated here rather than at the two
	9333	+ // payload call sites (Admin + Rest_Api) so `enabled`, `blocking` and
	9334	+ // `needs_review` are consistently gated on the same condition. (#108)
	9335	+ $opts = Settings::get();
	9336	+ if ( empty( $opts['cache_enabled'] ) ) {
1316	9337	return false;
1317	9338	}
1318		- $opts = Settings_Manager::get( 'cache' );
1319		- return empty( $opts['mobile_separate'] );
	9339	+ $cache_opts = Settings_Manager::get( 'cache' );
	9340	+ return ! empty( $cache_opts['mobile_separate_review'] );
1320	9341	}
1321	9342
	9343	+ /**
	9344	+ * Clear the review flag — called when the user has acted on the prompt
	9345	+ * (dismissed it, or turned Separate Mobile Cache on/off deliberately) so
	9346	+ * the dashboard callout doesn't nag forever. Writes the option directly
	9347	+ * (bypassing Settings_Manager) so it never touches schema fields.
	9348	+ */
	9349	+ public static function clear_mobile_separate_review(): void {
	9350	+ $stored = get_option( 'xspeed_module_cache', array() );
	9351	+ if ( ! is_array( $stored ) || empty( $stored['mobile_separate_review'] ) ) {
	9352	+ return;
	9353	+ }
	9354	+ unset( $stored['mobile_separate_review'] );
	9355	+ update_option( 'xspeed_module_cache', $stored );
	9356	+ }
	9357	+
	9358	+ /**
	9359	+ * On-demand probe: does the homepage serve materially the same HTML to a
	9360	+ * desktop and a mobile browser? Fetches home_url() twice over loopback —
	9361	+ * once with a desktop User-Agent, once with a mobile one — strips
	9362	+ * per-request noise (nonces, CSRF tokens, session ids, inline timestamps),
	9363	+ * and compares. When identical, Separate Mobile Cache is almost certainly
	9364	+ * unnecessary and the user can turn it off to regain the static fast path.
	9365	+ *
	9366	+ * NEVER run automatically (no page-load cost) — only from the dashboard
	9367	+ * "Check now" button. Result is cached for 10 minutes so a double-click or
	9368	+ * a re-render doesn't fire two more self-requests. (FBS-83145)
	9369	+ *
	9370	+ * @return array{ identical:bool, checked:bool, reason?:string, desktop_bytes?:int, mobile_bytes?:int }
	9371	+ */
	9372	+ public static function probe_mobile_equality(): array {
	9373	+ $cached = get_transient( 'xspeed_mobile_equality_probe' );
	9374	+ if ( is_array( $cached ) ) {
	9375	+ return $cached;
	9376	+ }
	9377	+
	9378	+ $home = home_url( '/' );
	9379	+ $host = (string) wp_parse_url( $home, PHP_URL_HOST );
	9380	+ if ( '' === $host ) {
	9381	+ $result = array( 'identical' => false, 'checked' => false, 'reason' => 'home_url has no host' );
	9382	+ set_transient( 'xspeed_mobile_equality_probe', $result, MINUTE_IN_SECONDS );
	9383	+ return $result;
	9384	+ }
	9385	+
	9386	+ // Match WP core's own mobile detection (wp_is_mobile) so the probe
	9387	+ // reflects what the site would actually branch on. iPhone Safari for
	9388	+ // mobile; a current desktop Chrome UA for desktop.
	9389	+ $desktop_ua = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
	9390	+ $mobile_ua = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
	9391	+
	9392	+ $is_local = function_exists( 'wp_get_environment_type' )
	9393	+ && in_array( wp_get_environment_type(), array( 'local', 'development' ), true );
	9394	+
	9395	+ $fetch = static function ( string $ua ) use ( $home, $is_local ) {
	9396	+ $resp = wp_remote_get(
	9397	+ $home,
	9398	+ array(
	9399	+ 'timeout' => 5,
	9400	+ 'sslverify' => ! $is_local,
	9401	+ 'redirection' => 2,
	9402	+ // Bust any per-device cache so we compare freshly-rendered
	9403	+ // HTML, and pass the device UA the site would branch on.
	9404	+ 'user-agent' => $ua,
	9405	+ // A real device UA by design, so only the header marks
	9406	+ // this as ours to analytics and the hit ratio.
	9407	+ 'headers' => Self_Traffic::headers( array( 'Cache-Control' => 'no-cache' ) ),
	9408	+ )
	9409	+ );
	9410	+ if ( is_wp_error( $resp ) || 200 !== (int) wp_remote_retrieve_response_code( $resp ) ) {
	9411	+ return null;
	9412	+ }
	9413	+ return (string) wp_remote_retrieve_body( $resp );
	9414	+ };
	9415	+
	9416	+ $desktop = $fetch( $desktop_ua );
	9417	+ $mobile = $fetch( $mobile_ua );
	9418	+
	9419	+ if ( null === $desktop || null === $mobile ) {
	9420	+ $result = array( 'identical' => false, 'checked' => false, 'reason' => 'could not fetch homepage twice' );
	9421	+ set_transient( 'xspeed_mobile_equality_probe', $result, MINUTE_IN_SECONDS );
	9422	+ return $result;
	9423	+ }
	9424	+
	9425	+ $identical = self::normalize_html_for_diff( $desktop ) === self::normalize_html_for_diff( $mobile );
	9426	+
	9427	+ $result = array(
	9428	+ 'identical' => $identical,
	9429	+ 'checked' => true,
	9430	+ 'desktop_bytes' => strlen( $desktop ),
	9431	+ 'mobile_bytes' => strlen( $mobile ),
	9432	+ );
	9433	+ set_transient( 'xspeed_mobile_equality_probe', $result, 10 * MINUTE_IN_SECONDS );
	9434	+ return $result;
	9435	+ }
	9436	+
	9437	+ /**
	9438	+ * Strip per-request noise from HTML so a desktop-vs-mobile diff reflects
	9439	+ * real structural differences, not nonces / session ids / timestamps that
	9440	+ * change on every render. Deliberately conservative: it normalizes the
	9441	+ * handful of well-known noise sources and collapses whitespace, so a site
	9442	+ * that truly serves different markup per device still compares as different.
	9443	+ */
	9444	+ private static function normalize_html_for_diff( string $html ): string {
	9445	+ // Every rule here errs toward "they differ" being WRONG rather than
	9446	+ // "they match" being wrong: this check only ever tells a user it is
	9447	+ // SAFE to turn Separate Mobile Cache off, so a false "identical"
	9448	+ // would cost them device-specific output. The risk of being too
	9449	+ // conservative is milder but real — the useful answer never appears,
	9450	+ // and the feature's whole pitch ("we'll prove it's safe to turn
	9451	+ // off") silently never pays out. These close the gaps that made a
	9452	+ // mismatch effectively guaranteed on an ordinary WordPress site. (#108)
	9453	+ $patterns = array(
	9454	+ // WP nonces in attribute or JSON form: data-nonce="…",
	9455	+ // _wpnonce=…, "nonce":"…". The `[:=]` adjacency below misses
	9456	+ // wp_nonce_field()'s own markup — `name="_wpnonce" value="ab…"`
	9457	+ // puts `value=` between the key and the token — which is the
	9458	+ // single most common nonce shape in WordPress, so that form is
	9459	+ // matched explicitly first.
	9460	+ '/name=["\']?(_wpnonce|_ajax_nonce)["\']?\s+value=["\']?[a-z0-9]{8,}/i',
	9461	+ // CSP nonces on script/style tags. Base64, so uppercase and
	9462	+ // +/= appear — the hex-only rules below can never match one,
	9463	+ // and a CSP-enabled site therefore differed on every fetch.
	9464	+ // MUST precede the generic nonce rule: that one stops at the
	9465	+ // first non-alphanumeric, leaving the rest of the token behind
	9466	+ // and the two responses still unequal.
	9467	+ // The quotes are optional so HTML5's legal unquoted attribute
	9468	+ // form (`<script nonce=AbCd+q/r=>`) is covered too — without
	9469	+ // that it fell through to the generic rule, which is the exact
	9470	+ // failure this rule exists to remove.
	9471	+ '/\bnonce=(["\'])?[A-Za-z0-9+\/=_-]{8,}(?(1)\1)/',
	9472	+ '/(_wpnonce|nonce|_ajax_nonce)["\']?\s*[:=]\s*["\']?[a-z0-9]{8,}/i',
	9473	+ // Generic hex tokens: cache busters, session ids, md5/sha
	9474	+ // digests. Was 16+, which left an 11-15 char gap above the
	9475	+ // 10-char nonce rule.
	9476	+ //
	9477	+ // The token MUST contain at least one a-f letter. `[a-f0-9]`
	9478	+ // also matches every decimal digit, so a bare `{10,}` erased
	9479	+ // every 10+ digit INTEGER anywhere in the document — including
	9480	+ // visible body text. A page whose desktop and mobile HTML
	9481	+ // differed only by a per-device numeric id (an AdSense slot, an
	9482	+ // A/B bucket, an analytics property) then compared as identical,
	9483	+ // and the check told the user it was safe to switch off the very
	9484	+ // setting keeping that output correct — the one direction this
	9485	+ // function must never fail in. Decimal-only runs are left to the
	9486	+ // bounded epoch rule below, which is deliberately narrower.
	9487	+ //
	9488	+ // Known, accepted (QA R2): a token whose letters all fall in a-f
	9489	+ // reads as a digest, so a per-device `ABC1234567890` strips even
	9490	+ // though it is an id, not a hash. Deliberately left open — the
	9491	+ // alternatives all cost more than the bug:
	9492	+ //
	9493	+ // Token shape (lowercase-only, case-uniformity, a trailing
	9494	+ // letter) cannot separate it. `ABC1234567890` and
	9495	+ // `ABCDEF012345` — an uppercase digest this rule SHOULD strip —
	9496	+ // are both all-hex, uniformly cased, letters-then-digits.
	9497	+ // Each variant fixed the id only by sparing the digest.
	9498	+ //
	9499	+ // Letter density does separate them (23% letters vs 50%), but
	9500	+ // measured over 2000 md5/sha1/sha256 samples, requiring letters
	9501	+ // spread through the token leaves 21-67% of REAL digests
	9502	+ // unmatched depending on the window. Digest noise is most of
	9503	+ // what this function exists to remove, so that trade guts it.
	9504	+ //
	9505	+ // Context (protecting data-* attribute values from this rule)
	9506	+ // works for ids and still strips digests in URLs, classes and
	9507	+ // query strings — but regresses a CHANGING digest inside a
	9508	+ // non-nonce data-* attribute, and needs a two-pass
	9509	+ // hold/restore. Viable if R2 is ever worth pressing; its
	9510	+ // failure at least errs toward "differ".
	9511	+ //
	9512	+ // An A-F-only prefix on a per-device id is rare, and the earlier
	9513	+ // nonce rules already claim the data-nonce/_wpnonce shapes.
	9514	+ '/\b(?=[a-f0-9]{10,}\b)[0-9]*[a-f][a-f0-9]*\b/i',
	9515	+ // wp-generated unique ids (e.g. wp-block ids, aria ids).
	9516	+ '/(id|for|aria-[a-z]+)="[^"]*-[0-9]{3,}"/i',
	9517	+ // ISO-ish timestamps + epoch-looking numbers in query strings.
	9518	+ '/\?ver=[0-9.]+/',
	9519	+ '/[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9:.+Z-]+/',
	9520	+ // Our own signature's generation stamp. The two fetches are
	9521	+ // sequential and each writes its own entry, so this differs on
	9522	+ // essentially every comparison — and it is space-separated, so
	9523	+ // the ISO rule above (which requires a literal `T`) never
	9524	+ // touches it. Without this the probe reports "differ" for every
	9525	+ // site and the "safe to turn Separate Mobile Cache off" verdict
	9526	+ // can never appear.
	9527	+ '/generated [0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2} UTC/',
	9528	+ // Raw epoch seconds. The two fetches are sequential, so any
	9529	+ // template printing time() guaranteed a mismatch.
	9530	+ //
	9531	+ // This is the ONLY rule that may strip a decimal-only run, so
	9532	+ // its bound is load-bearing rather than decorative — every digit
	9533	+ // it gives away is a class of per-device id it silently erases.
	9534	+ // `1[0-9]{9}` was too loose: it claimed the whole
	9535	+ // 1000000000-1999999999 range (2001-2033) to cover timestamps
	9536	+ // nobody serves, and took every 10-digit AdSense slot, order id
	9537	+ // and SKU beginning with 1 along with it — reproducing the exact
	9538	+ // false-"identical" verdict the hex rule above was tightened to
	9539	+ // stop. `1[6-9]` covers 2020-2033, which is the only span a live
	9540	+ // site can actually print, and collides with roughly a tenth as
	9541	+ // many ids.
	9542	+ //
	9543	+ // Not airtight — an id beginning 16-19 still collides. Closing
	9544	+ // that properly means scoping this to places a timestamp really
	9545	+ // appears (an attribute value, a query parameter, a JSON value)
	9546	+ // rather than bare body text; the bound is the cheap 90% of it.
	9547	+ '/\b1[6-9][0-9]{8}\b/',
	9548	+ );
	9549	+ $html = (string) preg_replace( $patterns, 'X', $html );
	9550	+ // Collapse all whitespace so trivial formatting differences don't count.
	9551	+ return trim( (string) preg_replace( '/\s+/', ' ', $html ) );
	9552	+ }
	9553	+
1322	9554	public static function ensure_hits_log_file(): bool {
	9555	+ // TWO writers append to this log, and an earlier fix conflated them:
	9556	+ //
	9557	+ // 1. nginx, via the server-level `access_log` directive in
	9558	+ // nginx_snippet() — a DIFFERENT uid, which is why the file needs
	9559	+ // to be world-writable there.
	9560	+ // 2. the PHP drop-in (advanced-cache.php), on EVERY server. A hit it
	9561	+ // serves bypasses WordPress entirely, so it can't call
	9562	+ // Hit_Counter::record_hit() — appending here is the only way that
	9563	+ // hit is ever counted.
	9564	+ //
	9565	+ // The nginx-only early return that used to sit at the top of this
	9566	+ // method was fixing something real: chmod() on a file PHP doesn't own
	9567	+ // raises "Operation not permitted", and off nginx that chmod buys
	9568	+ // nothing. But it took directory creation with it, so on LiteSpeed
	9569	+ // (which always serves via the drop-in), on Apache without mod_headers,
	9570	+ // and anywhere mobile_separate forces the drop-in path, writer 2 was
	9571	+ // appending to a file whose parent directory did not exist. The append
	9572	+ // is @-suppressed and documented as non-fatal, so every one of those
	9573	+ // hits vanished and the dashboard ratio sat at 0% forever.
	9574	+ //
	9575	+ // So: create the dir + file everywhere, and keep only the chmod gated
	9576	+ // to nginx.
1323	9577	$dir = self::hits_log_dir();
1324	9578	if ( ! is_dir( $dir ) && ! wp_mkdir_p( $dir ) ) {
1325	9579	return false;
1326	9580	}
1327		- // Ensure the dir is traversable + writable by a different-uid nginx.
1328		- // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- nginx (a separate uid in multi-container setups) must be able to create/append the log; WP_Filesystem layers ownership overrides that defeat that intent.
1329		- @chmod( $dir, 0777 ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort; the access_log just stays empty if it fails.
	9581	+
	9582	+ $is_nginx = ( Server::NGINX === Server::type() );
	9583	+
	9584	+ if ( $is_nginx ) {
	9585	+ // Ensure the dir is traversable + writable by a different-uid nginx.
	9586	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- nginx (a separate uid in multi-container setups) must be able to create/append the log; WP_Filesystem layers ownership overrides that defeat that intent.
	9587	+ @chmod( $dir, 0777 ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort; the access_log just stays empty if it fails.
	9588	+ }
	9589	+
1330	9590	$path = self::hits_log_path();
1331	9591	if ( ! file_exists( $path ) ) {
1332	9592	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_touch -- See docblock: must be a plain touch, not WP_Filesystem.
1333	9593	@touch( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- non-fatal helper; failures already covered by the dir check.
1334	9594	}
1335		- // World-writable so a different-uid nginx can append HIT lines.
1336		- // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- See docblock.
1337		- @chmod( $path, 0666 ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort.
	9595	+
	9596	+ if ( $is_nginx ) {
	9597	+ // World-writable so a different-uid nginx can append HIT lines.
	9598	+ // Off nginx the drop-in appends as the same uid that owns the file,
	9599	+ // so this is unnecessary — and would emit the "Operation not
	9600	+ // permitted" warnings the old early return was added to silence.
	9601	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_chmod -- See docblock.
	9602	+ @chmod( $path, 0666 ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort.
	9603	+ }
	9604	+
1338	9605	return file_exists( $path );
1339	9606	}
1340	9607
1341	9608	public static function nginx_snippet(): ?string {
		@@ -1399,9 +9666,55 @@
1399	9666	$lines[] = 'if ($http_host ~ "^([^:]+):(\\d+)$") { set $xspeed_host $1$2; }'; // host:port → hostport (matches PHP static_host())
1400	9667	$lines[] = 'set $xspeed_no_cache "no-cache";';
1401	9668	$lines[] = 'if ($request_method != GET) { set $xspeed_no_cache "$xspeed_no_cache-method"; }';
1402	9669	$lines[] = 'if ($args) { set $xspeed_no_cache "$xspeed_no_cache-args"; }';
1403		- $lines[] = 'if ($http_cookie ~* "(wordpress_logged_in|comment_author|wp-postpass_)") { set $xspeed_no_cache "$xspeed_no_cache-cookie"; }';
	9670	+ // Cookie + user-agent exclusions, generated from the user's actual
	9671	+ // settings rather than a hardcoded list. Before this, the rule
	9672	+ // tested three fixed cookie names and no user agent at all, so
	9673	+ // every excluded_cookies / bypass_user_agents entry applied only
	9674	+ // while a page was cold — on a warm page nginx served the shared
	9675	+ // anonymous copy to carts, members and bypassed bots alike. The
	9676	+ // three historical names survive as a floor inside cookie_rule().
	9677	+ // `~*` is case-insensitive, matching PHP's stripos()/glob checks.
	9678	+ // Stored read — reached from boot(); see stored_cache_opts(). The
	9679	+ // fallbacks below mirror the schema's own defaults, which a raw read
	9680	+ // does not apply.
	9681	+ $cache_opts = self::stored_cache_opts();
	9682	+ $cookie_rule = Server_Rules::cookie_rule(
	9683	+ is_array( $cache_opts['excluded_cookies'] ?? null )
	9684	+ ? $cache_opts['excluded_cookies']
	9685	+ : \XSpeed\Modules\Cache\CacheModule::DEFAULT_EXCLUDED_COOKIES
	9686	+ );
	9687	+ $lines[] = 'if ($http_cookie ~* "(' . $cookie_rule['regex'] . ')") { set $xspeed_no_cache "$xspeed_no_cache-cookie"; }';
	9688	+
	9689	+ $ua_rule = Server_Rules::user_agent_rule(
	9690	+ is_array( $cache_opts['bypass_user_agents'] ?? null ) ? $cache_opts['bypass_user_agents'] : array()
	9691	+ );
	9692	+ // Emitted only when the list is non-empty — an empty alternation
	9693	+ // would compile to `(...)` matching every request and disable the
	9694	+ // fast path entirely.
	9695	+ if ( '' !== $ua_rule['regex'] ) {
	9696	+ $lines[] = 'if ($http_user_agent ~* "(' . $ua_rule['regex'] . ')") { set $xspeed_no_cache "$xspeed_no_cache-ua"; }';
	9697	+ }
	9698	+
	9699	+ // URL exclusions. Without this an excluded URL was only excluded
	9700	+ // while its page was cold: PHP won't write a static file for one, so
	9701	+ // there is usually nothing to serve — but a page cached BEFORE the
	9702	+ // rule was added still has its file on disk, and nginx serves it
	9703	+ // without ever asking PHP. The exclusion then does nothing until the
	9704	+ // next purge. (#169)
	9705	+ //
	9706	+ // Matched against $uri, not $request_uri: $uri is the decoded path
	9707	+ // without the query string, which is what Cache::should_cache()
	9708	+ // tests. Using $request_uri would make `/cart` fail to match
	9709	+ // `/cart?x=1` inconsistently with PHP. Same empty-regex guard as the
	9710	+ // UA rule above — an empty alternation matches everything.
	9711	+ $url_rule = Server_Rules::url_rule(
	9712	+ is_array( $cache_opts['excluded_urls'] ?? null ) ? $cache_opts['excluded_urls'] : array()
	9713	+ );
	9714	+ if ( '' !== $url_rule['regex'] ) {
	9715	+ $lines[] = 'if ($uri ~* "(' . $url_rule['regex'] . ')") { set $xspeed_no_cache "$xspeed_no_cache-url"; }';
	9716	+ }
1404	9717	$lines[] = 'if (!-f "$document_root' . $rel . '/$xspeed_host$uri/index.html") { set $xspeed_no_cache "$xspeed_no_cache-nofile"; }';
1405	9718	// Neither `add_header` nor `access_log` is allowed inside an `if{}`
1406	9719	// at server level (nginx rejects with "directive is not allowed
1407	9720	// here"). The logging therefore lives in a `location` block that
		@@ -1431,10 +9744,41 @@
1431	9744	// missing. So: hits are logged, and a user deleting the log can't take
1432	9745	// nginx down.
1433	9746	$lines[] = ' access_log ' . $hits_abs . ' combined buffer=16k flush=5s;';
1434	9747	$lines[] = ' add_header X-XSpeed-Cache "HIT (nginx)" always;';
	9748	+ // Edge/CDN headers from the same seam the drop-in bakes. nginx serves
	9749	+ // this path without ever starting PHP, so the answer cannot be
	9750	+ // resolved per request — the pairs are resolved HERE, when the
	9751	+ // snippet is generated, and a change of answer needs the snippet
	9752	+ // regenerated and re-pasted to take effect.
	9753	+ //
	9754	+ // Skipped entirely when the static path is switched off. The only
	9755	+ // reason that can fire under `bake` is mobile-split, and mobile-split
	9756	+ // is also what switches the static path off — so the block would be
	9757	+ // baked with a hold it can never serve, and would start serving it
	9758	+ // the moment the setting is turned off and static files reappear,
	9759	+ // until somebody regenerates and re-pastes. A rule that can only be
	9760	+ // served once its premise is false is guaranteed to be stale.
	9761	+ foreach ( self::static_rewrite_allowed() ? self::edge_headers_for( 'HIT', 'rules' ) : array() as $name => $value ) {
	9762	+ $lines[] = ' add_header ' . $name . ' "' . self::quote_directive_value( $value ) . '" always;';
	9763	+ }
1435	9764	$lines[] = '}';
1436		- return implode( "\n", $lines );
	9765	+
	9766	+ // Stamp the block with a hash of itself. This is the only way to find
	9767	+ // out what a user actually pasted: the block lives in a server config
	9768	+ // WordPress cannot read, so until now the dashboard could not tell an
	9769	+ // up-to-date paste from one made three settings changes ago, and
	9770	+ // covered for that by telling everyone to re-paste after every save.
	9771	+ // A hit through this location now carries the version that served it
	9772	+ // and probe_static_rewrite() reads it back. See rules_state().
	9773	+ return implode(
	9774	+ "\n",
	9775	+ self::with_rules_marker(
	9776	+ $lines,
	9777	+ array( ' add_header ' . self::RULES_HEADER . ' "%s" always;' ),
	9778	+ count( $lines ) - 1
	9779	+ )
	9780	+ );
1437	9781	}
1438	9782
1439	9783	/**
1440	9784	* Aggregate every enabled module's nginx_directives() into one
		@@ -1490,11 +9834,13 @@
1490	9834	* static-cache tree (with the X-XSpeed-Cache header + access-log HIT
1491	9835	* accounting), and PHP/the drop-in is the fallback. To guarantee
1492	9836	* LSCache doesn't shadow that with its own copy — some LiteSpeed
1493	9837	* configs cache by default — we send an explicit `no-cache` control so
1494		- * the server defers to our rewrite. Skipped when the LiteSpeed Cache
1495		- * plugin is active (it owns its own header policy; our Conflict
1496		- * registry handles that coexistence separately).
	9838	+ * the server defers to our rewrite. Skipped while the LiteSpeed Cache
	9839	+ * plugin's page cache may be on: it owns its own header policy then,
	9840	+ * and enabling ours is refused while its page cache is on (#653). With
	9841	+ * its page cache provably off, xSpeed owns the cache exactly as when
	9842	+ * the plugin is absent, so the stand-down is sent.
1497	9843	*/
1498	9844	public static function maybe_emit_lscache_headers(): void {
1499	9845	if ( headers_sent() ) {
1500	9846	return;
		@@ -1505,9 +9851,10 @@
1505	9851	// is_plugin_active() lives in wp-admin/includes/plugin.php which
1506	9852	// isn't auto-loaded on front-end requests. Use the option layer
1507	9853	// directly to avoid pulling in admin code from a render path.
1508	9854	$active = (array) get_option( 'active_plugins', array() );
1509		- if ( in_array( 'litespeed-cache/litespeed-cache.php', $active, true ) ) {
	9855	+ if ( in_array( 'litespeed-cache/litespeed-cache.php', $active, true )
	9856	+ && false !== Cache_Plugin_Catalog::litespeed_page_cache_state() ) {
1510	9857	return;
1511	9858	}
1512	9859
1513	9860	// Explicitly opt this response OUT of LSCache so the server can't
		@@ -1515,8 +9862,62 @@
1515	9862	header( 'X-LiteSpeed-Cache-Control: no-cache' );
1516	9863	}
1517	9864
1518	9865	/**
	9866	+ * Restore the drop-in + WP_CACHE constant for a site that had caching
	9867	+ * ON before this activation — and ONLY for such a site.
	9868	+ *
	9869	+ * WordPress runs an upgrade as deactivate → wipe plugin files →
	9870	+ * install → activate. The wipe takes advanced-cache.php with it, so
	9871	+ * without this the site serves 100% uncached from the moment the
	9872	+ * update finishes until the next authenticated wp-admin page load
	9873	+ * (auto_heal() is on admin_init). On a site whose admin logs in
	9874	+ * rarely that window is hours or days of silent cache loss, while
	9875	+ * the dashboard still reports cache_enabled = true. (FBS field
	9876	+ * report against 1.1.2 / Pro 1.0.5.)
	9877	+ *
	9878	+ * The `cache_enabled` guard is the whole contract: a FRESH install
	9879	+ * has the option unset, so activation writes nothing and the user
	9880	+ * still opts in explicitly through Cache::toggle() via the
	9881	+ * /cache/toggle REST endpoint. We only ever put back state the user
	9882	+ * already chose — repair, never a new install path. This is what
	9883	+ * keeps us on the right side of the "don't create drop-ins the user
	9884	+ * didn't ask for" guideline while matching what WP Rocket, W3 Total
	9885	+ * Cache and WP Super Cache all do on activation.
	9886	+ *
	9887	+ * @return bool True when a restore was performed.
	9888	+ */
	9889	+ public static function restore_dropin_if_enabled(): bool {
	9890	+ if ( defined( 'WP_INSTALLING' ) && WP_INSTALLING ) {
	9891	+ return false;
	9892	+ }
	9893	+
	9894	+ // The user's saved choice. Absent/false on a fresh install => no
	9895	+ // drop-in is written and nothing touches wp-config.php.
	9896	+ $opts = get_option( 'xspeed_options', array() );
	9897	+ if ( empty( $opts['cache_enabled'] ) ) {
	9898	+ return false;
	9899	+ }
	9900	+
	9901	+ $state = self::toggle( true, false );
	9902	+ // A refusal reports whether the cache SERVES, which on this path can
	9903	+ // be true for reasons that have nothing to do with this call — so a
	9904	+ // refusal would otherwise log "drop-in restored" for a restore that
	9905	+ // was declined. Restored means the transaction went through.
	9906	+ $restored = empty( $state['blocked'] ) && ! empty( $state['enabled'] );
	9907	+
	9908	+ if ( $restored ) {
	9909	+ Activity_Log::record(
	9910	+ 'cache_dropin_restored',
	9911	+ 'Cache drop-in restored after a plugin update — caching was already enabled.',
	9912	+ Activity_Log::SUCCESS
	9913	+ );
	9914	+ }
	9915	+
	9916	+ return $restored;
	9917	+ }
	9918	+
	9919	+ /**
1519	9920	* Reconcile drop-in + WP_CACHE + rewrite block with the user's
1520	9921	* saved choice. Runs on admin_init. Cheap when nothing's wrong
1521	9922	* (one option read + a handful of file_exists / defined checks);
1522	9923	* writes only when state has drifted (typical cause: plugin
		@@ -1538,32 +9939,16 @@
1538	9939	if ( empty( $opts['cache_enabled'] ) ) {
1539	9940	return;
1540	9941	}
1541	9942
1542		- $dropin_target = WP_CONTENT_DIR . '/advanced-cache.php';
1543		- $dropin_ours = false;
1544		- $dropin_stale = false;
1545		- if ( file_exists( $dropin_target ) ) {
1546		- $contents = @file_get_contents( $dropin_target ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
1547		- $dropin_ours = is_string( $contents ) && false !== strpos( $contents, 'XSPEED_DROPIN' );
1548		- // Reinstall when OUR drop-in is an older version than the source —
1549		- // the marker alone can't distinguish an old copy from a new one, so
1550		- // a serve-logic change (e.g. the .meta read for 404s/feeds) would
1551		- // otherwise never reach existing cache-enabled sites until a manual
1552		- // cache toggle. (FBS-82406/82407)
1553		- if ( $dropin_ours ) {
1554		- $dropin_stale = self::dropin_version( (string) $contents ) < self::dropin_version( @file_get_contents( XSPEED_DIR . 'includes/advanced-cache.php' ) ?: '' ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
1555		- }
	9943	+ $state = self::toggle( true, false );
	9944	+ // A refusal means something else now owns the page-cache field, or
	9945	+ // the write could not be verified. Either way this is not the moment
	9946	+ // to go on maintaining our rewrite block and log file.
	9947	+ if ( ! empty( $state['blocked'] ) || empty( $state['enabled'] ) ) {
	9948	+ return;
1556	9949	}
1557	9950
1558		- if ( ! $dropin_ours || $dropin_stale ) {
1559		- self::install_dropin();
1560		- }
1561		-
1562		- if ( ! defined( 'WP_CACHE' ) || ! WP_CACHE ) {
1563		- self::set_wp_cache_constant( true );
1564		- }
1565		-
1566	9951	// Rewrite block goes last. It's what turns the static-cache
1567	9952	// tree into a PHP-bypass — every cache hit served by the web
1568	9953	// server directly. Without it we still cache, just at drop-in
1569	9954	// speed (~85ms TTFB) instead of static-file speed (~25-40ms).
		@@ -1588,8 +9973,54 @@
1588	9973	self::ensure_hits_log_file();
1589	9974	}
1590	9975
1591	9976	/**
	9977	+ * Keep the generic bypass cookie in sync with PHP's caching verdict.
	9978	+ *
	9979	+ * The server config tests exactly one cookie name (Server_Rules::
	9980	+ * BYPASS_COOKIE) forever, and PHP decides what that name means. Adding
	9981	+ * a new excluded cookie therefore needs no config change and no nginx
	9982	+ * reload — the reason this exists.
	9983	+ *
	9984	+ * Session cookie (expiry 0) so it dies with the browser session, and
	9985	+ * deliberately NOT HttpOnly-sensitive: it carries no identity, only the
	9986	+ * boolean "don't serve this visitor a shared cached page".
	9987	+ *
	9988	+ * Honest limit: this can only ever help a visitor PHP has already seen
	9989	+ * once. A bot's first request to a warm page never reaches PHP, which
	9990	+ * is why user-agent rules are still written into the server config
	9991	+ * rather than relying on this.
	9992	+ *
	9993	+ * @param bool $bypass Whether this visitor must skip the cache.
	9994	+ */
	9995	+ private static function sync_bypass_cookie( bool $bypass ): void {
	9996	+ if ( headers_sent() ) {
	9997	+ return;
	9998	+ }
	9999	+
	10000	+ $name = Server_Rules::BYPASS_COOKIE;
	10001	+ $has = isset( $_COOKIE[ $name ] );
	10002	+
	10003	+ // Only touch the header when the state actually changes — a
	10004	+ // Set-Cookie on every request would make the response uncacheable
	10005	+ // for intermediary caches and add noise to every hit.
	10006	+ if ( $bypass === $has ) {
	10007	+ return;
	10008	+ }
	10009	+
	10010	+ $path = defined( 'COOKIEPATH' ) && COOKIEPATH ? COOKIEPATH : '/';
	10011	+ $domain = defined( 'COOKIE_DOMAIN' ) ? COOKIE_DOMAIN : '';
	10012	+
	10013	+ if ( $bypass ) {
	10014	+ setcookie( $name, '1', 0, $path, (string) $domain, is_ssl(), false );
	10015	+ $_COOKIE[ $name ] = '1';
	10016	+ } else {
	10017	+ setcookie( $name, '', time() - 3600, $path, (string) $domain, is_ssl(), false );
	10018	+ unset( $_COOKIE[ $name ] );
	10019	+ }
	10020	+ }
	10021	+
	10022	+ /**
1592	10023	* Build the .htaccess rules that map cacheable requests to the
1593	10024	* static-cache tree. Conditions are deliberately strict: GET only,
1594	10025	* empty query string, no session/comment-author/post-password
1595	10026	* cookie, and the static file must exist on disk. Anything that
		@@ -1606,14 +10037,46 @@
1606	10037	$rel = str_replace( ABSPATH, '/', XSPEED_CACHE_STATIC_DIR );
1607	10038	$rel = '/' . ltrim( $rel, '/' );
1608	10039	$rel = rtrim( $rel, '/' );
1609	10040
1610		- return array(
	10041	+ // Cookie + user-agent exclusions generated from the live settings.
	10042	+ // See the matching block in nginx_snippet() — same generator, same
	10043	+ // floor, so both servers enforce an identical policy. Apache reads
	10044	+ // .htaccess on every request and we already self-heal this file, so
	10045	+ // Apache/LiteSpeed users get the fix on upgrade with no action.
	10046	+ $cache_opts = Settings_Manager::get( 'cache' );
	10047	+ $cookie_rule = Server_Rules::cookie_rule(
	10048	+ is_array( $cache_opts['excluded_cookies'] ?? null ) ? $cache_opts['excluded_cookies'] : array()
	10049	+ );
	10050	+ $ua_rule = Server_Rules::user_agent_rule(
	10051	+ is_array( $cache_opts['bypass_user_agents'] ?? null ) ? $cache_opts['bypass_user_agents'] : array()
	10052	+ );
	10053	+
	10054	+ $lines = array(
1611	10055	'<IfModule mod_rewrite.c>',
1612	10056	' RewriteEngine On',
1613	10057	' RewriteCond %{REQUEST_METHOD} ^GET$',
1614	10058	' RewriteCond %{QUERY_STRING} ^$',
1615		- ' RewriteCond %{HTTP_COOKIE} !(wordpress_logged_in|comment_author|wp-postpass_) [NC]',
	10059	+ ' RewriteCond %{HTTP_COOKIE} !(' . $cookie_rule['regex'] . ') [NC]',
	10060	+ );
	10061	+
	10062	+ // Only emit the UA condition when there's something to match —
	10063	+ // `!()` would negate an always-true empty match and refuse every
	10064	+ // request, silently disabling the static path.
	10065	+ if ( '' !== $ua_rule['regex'] ) {
	10066	+ // Quoted, because RewriteCond is whitespace-delimited and real
	10067	+ // user-agent fragments contain spaces ("Mozilla/5.0 (compatible").
	10068	+ // Unquoted, a space adds an argument and Apache answers every
	10069	+ // request with a 500 — and because .htaccess is parsed per
	10070	+ // request, `httpd -t` still reports Syntax OK. Server_Rules has
	10071	+ // already excluded quotes and backslashes from the alternation,
	10072	+ // so the closing quote here cannot be escaped away.
	10073	+ $lines[] = ' RewriteCond %{HTTP_USER_AGENT} "!(' . $ua_rule['regex'] . ')" [NC]';
	10074	+ }
	10075	+
	10076	+ $block = array_merge(
	10077	+ $lines,
	10078	+ array(
1616	10079	// Capture REQUEST_URI without its trailing slash into %1.
1617	10080	// store_static() writes `{host}{uri-without-trailing-slash}/index.html`,
1618	10081	// so this normalization lets `/blog/` and `/blog` both hit
1619	10082	// the same cache file without producing the double-slash
		@@ -1629,11 +10092,83 @@
1629	10092	// `^` matches the empty string AND any non-empty path, so it
1630	10093	// covers `/` and `/blog` alike. (Confirmed on OpenLiteSpeed
1631	10094	// 1.8: `.` → homepage served by PHP drop-in; `^` → served
1632	10095	// directly from the static file.)
1633		- ' RewriteRule ^ ' . $rel . '/%{HTTP_HOST}%1/index.html [L]',
	10096	+ // `E=` tags the request the rewrite just served from the cache
	10097	+ // tree. The edge headers below key off it instead of the file
	10098	+ // name: <FilesMatch "\.html$"> in a document-root .htaccess
	10099	+ // matches EVERY .html on the site — a hand-uploaded /promo.html,
	10100	+ // a static export — and telling a CDN to hold those for the page
	10101	+ // TTL would pin files xSpeed never wrote and cannot purge.
	10102	+ ' RewriteRule ^ ' . $rel . '/%{HTTP_HOST}%1/index.html [E=XSPEED_STATIC_HIT:1,L]',
1634	10103	'</IfModule>',
	10104	+ // Mark the statically-served response as a cache HIT.
	10105	+ //
	10106	+ // A file served by the rewrite above bypasses PHP entirely, so
	10107	+ // this directive is the ONLY thing that can identify it as
	10108	+ // cached — both for the user reading response headers and for
	10109	+ // Hit_Counter, which reconciles static hits from the access
	10110	+ // log. Without it the cache works perfectly and reports a 0%
	10111	+ // hit ratio, which reads as "the plugin is broken". (Field
	10112	+ // report against 1.1.2: homepage served byte-identical from
	10113	+ // the static tree, no X-XSpeed-Cache header on any response.)
	10114	+ //
	10115	+ // `always` so the header is set on the 200 from the rewritten
	10116	+ // file, not only on the successful-response table. The
	10117	+ // <IfModule> guard keeps a server without mod_headers from
	10118	+ // 500ing on an unknown directive — on such a host the header
	10119	+ // is silently dropped, which is exactly why
	10120	+ // static_rewrite_allowed() refuses the static path there and
	10121	+ // routes hits through the drop-in instead.
	10122	+ '<IfModule mod_headers.c>',
	10123	+ ' <FilesMatch "\\.html$">',
	10124	+ ' Header always set X-XSpeed-Cache "HIT (static)"',
	10125	+ ' </FilesMatch>',
	10126	+ )
1635	10127	);
	10128	+
	10129	+ // Edge/CDN headers from the same seam the drop-in bakes. Like the
	10130	+ // nginx snippet, the static rewrite answers without PHP, so the pairs
	10131	+ // are resolved when the block is GENERATED rather than per request.
	10132	+ //
	10133	+ // `env=` rather than the `<FilesMatch>` scoping above, because these
	10134	+ // must ride only on responses the rewrite produced. The X-XSpeed-Cache
	10135	+ // marker stays filename-scoped: it is inert, and narrowing it would
	10136	+ // change a header QA reads.
	10137	+ //
	10138	+ // Same reasoning as the nginx snippet: a bake hold can only come from
	10139	+ // mobile-split, and mobile-split is what turns this path off, so a
	10140	+ // hold baked here could only ever be served once its own premise had
	10141	+ // stopped being true.
	10142	+ $edge_lines = array();
	10143	+ foreach ( self::static_rewrite_allowed() ? self::edge_headers_for( 'HIT', 'rules' ) : array() as $edge_name => $edge_value ) {
	10144	+ $edge_lines = array_merge(
	10145	+ $edge_lines,
	10146	+ self::static_hit_directives(
	10147	+ ' Header always set ' . $edge_name . ' "' . self::quote_directive_value( $edge_value ) . '"'
	10148	+ )
	10149	+ );
	10150	+ }
	10151	+
	10152	+ $block = array_merge( $block, $edge_lines, array( '</IfModule>' ) );
	10153	+
	10154	+ // Same self-describing marker as the nginx snippet. Apache's block is
	10155	+ // written by us rather than pasted by hand, so it should never be out
	10156	+ // of date — but "should" is what refresh_rewrite_if_installed() not
	10157	+ // running looks like from the outside, and the probe can now say so
	10158	+ // instead of assuming. `env=` keeps it on responses the rewrite
	10159	+ // produced, so a hand-uploaded .html never claims to be our cache.
	10160	+ //
	10161	+ // Spliced in after the edge headers so the hash covers them: a
	10162	+ // changed edge answer has to make an installed block report itself
	10163	+ // stale, and a marker computed before they were appended would not
	10164	+ // move. The splice point steps back over them and `</IfModule>` to
	10165	+ // land inside `<FilesMatch>`, beside the X-XSpeed-Cache marker.
	10166	+ return self::with_rules_marker(
	10167	+ $block,
	10168	+ self::static_hit_directives( ' Header always set ' . self::RULES_HEADER . ' "%s"' ),
	10169	+ count( $block ) - count( $edge_lines ) - 2
	10170	+ );
1636	10171	}
1637	10172
1638	10173	/**
1639	10174	* Active probe that confirms the web-server static-rewrite path is
		@@ -1660,8 +10195,21 @@
1660	10195	* synchronously on every dashboard bootstrap, so a slow/timing-out
1661	10196	* loopback request added up to `timeout` seconds to admin page loads on
1662	10197	* hosts that block self-requests. (FBS-82142)
1663	10198	*/
	10199	+ /**
	10200	+ * Discard the cached probe result and run a fresh one.
	10201	+ *
	10202	+ * Without this there was no way to re-check: the result sat in a transient
	10203	+ * for five minutes and nothing ever deleted it, so a user who fixed their
	10204	+ * nginx config kept seeing "nginx detected — configure for max cache speed"
	10205	+ * with no means of confirming the fix worked. (FBS-84012)
	10206	+ */
	10207	+ public static function recheck_static_rewrite(): array {
	10208	+ delete_transient( 'xspeed_rewrite_probe' );
	10209	+ return self::probe_static_rewrite( true );
	10210	+ }
	10211	+
1664	10212	public static function probe_static_rewrite( bool $allow_probe = false ): array {
1665	10213	$cached = get_transient( 'xspeed_rewrite_probe' );
1666	10214	if ( is_array( $cached ) ) {
1667	10215	return $cached;
		@@ -1675,9 +10223,12 @@
1675	10223
1676	10224	$home = home_url( '/' );
1677	10225	$host = (string) wp_parse_url( $home, PHP_URL_HOST );
1678	10226	if ( '' === $host ) {
1679		- $result = array( 'active' => false, 'reason' => 'home_url has no host' );
	10227	+ // Environmental failure, not evidence the server config is wrong —
	10228	+ // mark it inconclusive so Health surfaces say "could not verify"
	10229	+ // instead of demanding a snippet paste. (#480)
	10230	+ $result = array( 'active' => false, 'inconclusive' => true, 'reason' => 'home_url has no host' );
1680	10231	set_transient( 'xspeed_rewrite_probe', $result, MINUTE_IN_SECONDS );
1681	10232	return $result;
1682	10233	}
1683	10234
		@@ -1694,9 +10245,12 @@
1694	10245	if ( ! file_exists( $probe_dir ) ) {
1695	10246	wp_mkdir_p( $probe_dir );
1696	10247	}
1697	10248	if ( ! is_dir( $probe_dir ) ) {
1698		- $result = array( 'active' => false, 'reason' => 'cannot create probe dir' );
	10249	+ // A cache-dir permissions problem — the probe never ran, so this
	10250	+ // says nothing about the nginx config. Inconclusive, not
	10251	+ // "required". (#480)
	10252	+ $result = array( 'active' => false, 'inconclusive' => true, 'reason' => 'cannot create probe dir' );
1699	10253	set_transient( 'xspeed_rewrite_probe', $result, MINUTE_IN_SECONDS );
1700	10254	return $result;
1701	10255	}
1702	10256	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents -- WP_Filesystem requires admin credentials we may not have here; the file is in our own cache dir.
		@@ -1716,9 +10270,9 @@
1716	10270	// don't repeat the wait every minute.
1717	10271	'timeout' => 3,
1718	10272	'sslverify' => ! $is_local,
1719	10273	'redirection' => 0,
1720		- 'headers' => array( 'Cache-Control' => 'no-cache' ),
	10274	+ 'headers' => Self_Traffic::headers( array( 'Cache-Control' => 'no-cache' ) ),
1721	10275	)
1722	10276	);
1723	10277
1724	10278	// Best-effort cleanup so we don't accumulate probe dirs even
		@@ -1733,8 +10287,14 @@
1733	10287
1734	10288	if ( is_wp_error( $resp ) ) {
1735	10289	$result = array(
1736	10290	'active' => false,
	10291	+ // The request never completed, so we learned NOTHING about the
	10292	+ // rewrite. Flagged inconclusive so the UI doesn't tell the user
	10293	+ // to configure a server that may already be configured — a
	10294	+ // blocked loopback, a self-signed cert, or a timeout is a probe
	10295	+ // failure, not a missing rewrite. (FBS-84012)
	10296	+ 'inconclusive' => true,
1737	10297	'reason' => 'http error: ' . $resp->get_error_message(),
1738	10298	);
1739	10299	// Cache the failure for the full 5 minutes (not 1) so a host that
1740	10300	// times out on the loopback probe isn't re-probed — and re-stalled
		@@ -1748,8 +10308,17 @@
1748	10308	$ua_php = '' !== (string) wp_remote_retrieve_header( $resp, 'x-powered-by' );
1749	10309	$has_etag = '' !== (string) wp_remote_retrieve_header( $resp, 'etag' )
1750	10310	|| '' !== (string) wp_remote_retrieve_header( $resp, 'last-modified' );
1751	10311	$match = trim( $body ) === $nonce;
	10312	+ // Which version of our generated rules answered, if any. Only the
	10313	+ // static path can set this — it is baked into the rules themselves —
	10314	+ // so its presence is direct evidence about what is installed, and its
	10315	+ // absence on a conclusive probe is evidence too. See rules_state().
	10316	+ // Validated to the shape we generate, so a proxy or another plugin
	10317	+ // sending something else under this name cannot be mistaken for a
	10318	+ // rules version and reported as "out of date".
	10319	+ $rules_raw = trim( (string) wp_remote_retrieve_header( $resp, strtolower( self::RULES_HEADER ) ) );
	10320	+ $rules = preg_match( '/^[0-9a-f]{8}\z/', $rules_raw ) ? $rules_raw : '';
1752	10321
1753	10322	// "Active" = the web server served our raw nonce bytes back
1754	10323	// AND emitted the static-serve markers (ETag / Last-Modified)
1755	10324	// AND didn't add an X-Powered-By: PHP header. All three are
		@@ -1755,25 +10324,42 @@
1755	10324	// AND didn't add an X-Powered-By: PHP header. All three are
1756	10325	// individually noisy; together they're conclusive.
1757	10326	$active = $match && $has_etag && ! $ua_php && 200 === $code;
1758	10327
	10328	+ /*
	10329	+ * `inconclusive` separates "we proved the rewrite isn't serving" from
	10330	+ * "the probe couldn't tell". Only the former should drive a
	10331	+ * configure-your-server banner; the latter previously rendered the
	10332	+ * same alarming copy at a user who had already configured nginx
	10333	+ * correctly, and there was no way to clear it. (FBS-84012)
	10334	+ */
	10335	+ $inconclusive = false;
1759	10336	if ( $active ) {
1760	10337	$reason = 'static-served';
1761	10338	} elseif ( 200 === $code && $match && $ua_php ) {
1762	10339	$reason = 'php served the file instead of nginx/Apache (rewrite block missing)';
1763	10340	} elseif ( 200 === $code && ! $match ) {
1764		- $reason = 'unexpected body (CDN cached an older response?)';
	10341	+ // Something answered 200 with content that isn't our nonce — a CDN,
	10342	+ // a proxy, a security plugin. That tells us nothing about the
	10343	+ // origin's rewrite.
	10344	+ $reason = 'unexpected body (CDN cached an older response?)';
	10345	+ $inconclusive = true;
1765	10346	} elseif ( 404 === $code ) {
1766	10347	$reason = 'probe URL returned 404 (rewrite block missing or wrong path)';
1767	10348	} else {
1768		- $reason = sprintf( 'unexpected response (HTTP %d, body %d B, php=%s)', $code, strlen( $body ), $ua_php ? 'yes' : 'no' );
	10349	+ // Redirects, 403s from a WAF, 5xx — the probe never reached a
	10350	+ // verdict about the rewrite itself.
	10351	+ $reason = sprintf( 'unexpected response (HTTP %d, body %d B, php=%s)', $code, strlen( $body ), $ua_php ? 'yes' : 'no' );
	10352	+ $inconclusive = true;
1769	10353	}
1770	10354
1771	10355	$result = array(
1772		- 'active' => $active,
1773		- 'reason' => $reason,
1774		- 'code' => $code,
1775		- 'php' => $ua_php,
	10356	+ 'active' => $active,
	10357	+ 'inconclusive' => $inconclusive,
	10358	+ 'reason' => $reason,
	10359	+ 'code' => $code,
	10360	+ 'php' => $ua_php,
	10361	+ 'rules' => $rules,
1776	10362	);
1777	10363	set_transient( 'xspeed_rewrite_probe', $result, 5 * MINUTE_IN_SECONDS );
1778	10364	return $result;
1779	10365	}
		@@ -1830,12 +10416,49 @@
1830	10416	$cleaned = self::strip_marker_block( $existing, 'xSpeed Static Cache' );
1831	10417	$block = self::marker_block( 'xSpeed Static Cache', self::rewrite_block_lines() );
1832	10418	$next = $block . ( '' === $cleaned ? '' : "\n" . $cleaned );
1833	10419
	10420	+ /*
	10421	+ * Nothing to change. auto_heal() runs the whole enable transaction on
	10422	+ * every admin_init and this is called unconditionally from it, so
	10423	+ * without this every wp-admin request truncated and rewrote .htaccess
	10424	+ * with byte-identical content. Apache reads that file without a lock,
	10425	+ * so the truncate window is a real 500 on a busy admin, and the churn
	10426	+ * trips host file-integrity monitors.
	10427	+ */
	10428	+ if ( $next === $existing ) {
	10429	+ return true;
	10430	+ }
	10431	+
1834	10432	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_put_contents_file_put_contents, PluginCheck.CodeAnalysis.WriteFile.ABSPATHDetected -- WP_Filesystem requires admin credentials we don't have here; toggle() runs in a REST request authorized by manage_options nonce. The target is the site's .htaccess (configuration file managed by WP core itself), not user data — wp_upload_dir() doesn't apply.
1835	10433	return false !== file_put_contents( $htaccess, $next, LOCK_EX );
1836	10434	}
1837	10435
	10436	+ /**
	10437	+ * Rewrite the .htaccess block in place when — and only when — one is
	10438	+ * already installed.
	10439	+ *
	10440	+ * The block embeds the generated cookie / user-agent exclusion rules,
	10441	+ * so it goes stale the moment those settings change. install_rewrite()
	10442	+ * regenerates it from the live settings, but calling that unconditionally
	10443	+ * on every save would CREATE a block on sites that never enabled the
	10444	+ * static path — silently turning on server-level serving nobody asked
	10445	+ * for. So we refresh only what's already there.
	10446	+ *
	10447	+ * @return bool True when a block was present and rewritten.
	10448	+ */
	10449	+ public static function refresh_rewrite_if_installed(): bool {
	10450	+ $htaccess = ABSPATH . '.htaccess';
	10451	+ if ( ! file_exists( $htaccess ) ) {
	10452	+ return false;
	10453	+ }
	10454	+ $existing = @file_get_contents( $htaccess ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- Best-effort read; an unreadable file simply means nothing to refresh.
	10455	+ if ( ! is_string( $existing ) || false === strpos( $existing, '# BEGIN xSpeed Static Cache' ) ) {
	10456	+ return false;
	10457	+ }
	10458	+ return self::install_rewrite();
	10459	+ }
	10460	+
1838	10461	public static function remove_rewrite(): bool {
1839	10462	$htaccess = ABSPATH . '.htaccess';
1840	10463	// phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_is_writable -- See install_rewrite() rationale.
1841	10464	if ( ! file_exists( $htaccess ) || ! is_writable( $htaccess ) ) {
		@@ -1856,9 +10479,21 @@
1856	10479	* follows it. Idempotent — returns the input unchanged if the
1857	10480	* marker isn't present.
1858	10481	*/
1859	10482	private static function strip_marker_block( string $contents, string $marker ): string {
1860		- $pattern = '/# BEGIN ' . preg_quote( $marker, '/' ) . '\b.*?# END ' . preg_quote( $marker, '/' ) . "\b[^\n]*\n?\n?/s";
	10483	+ /*
	10484	+ * The body may not contain another BEGIN for this marker.
	10485	+ *
	10486	+ * `.*?` is non-greedy but still spans anything, so an ORPHANED
	10487	+ * `# BEGIN xSpeed Static Cache` — an END line lost to a hand edit or
	10488	+ * a partial write — paired with the END of the NEXT block and deleted
	10489	+ * everything between them. On a site where the orphan sits above
	10490	+ * `# BEGIN WordPress`, that takes WordPress's own rewrite rules with
	10491	+ * it and every permalink 404s. Refusing to cross a second BEGIN makes
	10492	+ * the orphan a no-op instead of a site-wide outage.
	10493	+ */
	10494	+ $begin = '# BEGIN ' . preg_quote( $marker, '/' ) . '\b';
	10495	+ $pattern = '/' . $begin . '(?:(?!' . $begin . ').)*?# END ' . preg_quote( $marker, '/' ) . "\b[^\n]*\n?\n?/s";
1861	10496	$out = preg_replace( $pattern, '', $contents );
1862	10497	return is_string( $out ) ? $out : $contents;
1863	10498	}
1864	10499
		@@ -1882,8 +10517,426 @@
1882	10517	}
1883	10518	return 0;
1884	10519	}
1885	10520
	10521	+ /** The advanced-cache.php drop-in is ours. */
	10522	+ public const DROPIN_XSPEED = 'xspeed';
	10523	+ /** Someone else's drop-in is installed. */
	10524	+ public const DROPIN_FOREIGN = 'foreign';
	10525	+ /** No drop-in installed. */
	10526	+ public const DROPIN_NONE = 'none';
	10527	+ /** A drop-in is installed and we could not read it. */
	10528	+ public const DROPIN_UNREADABLE = 'unreadable';
	10529	+ /**
	10530	+ * Present but holding nothing -- empty, or whitespace only. WP Rocket
	10531	+ * truncates advanced-cache.php to 0 bytes on deactivate, and calling that
	10532	+ * FOREIGN made it a permanent blocker with no owner to ask. (#391)
	10533	+ */
	10534	+ public const DROPIN_ABANDONED = 'abandoned';
	10535	+
	10536	+ /**
	10537	+ * Who owns wp-content/advanced-cache.php right now.
	10538	+ *
	10539	+ * WordPress gives every caching plugin the same single file to live in,
	10540	+ * so "is there a drop-in" and "is it ours" are completely different
	10541	+ * questions, and only the second one licenses a write. An unreadable
	10542	+ * drop-in is deliberately its own answer rather than folding into
	10543	+ * "foreign": we cannot even name what we would be destroying.
	10544	+ *
	10545	+ * @return string One of the DROPIN_* constants.
	10546	+ */
	10547	+ public static function dropin_owner(): string {
	10548	+ require_once XSPEED_DIR . 'includes/wp-cache-constant.php';
	10549	+ $target = WP_CONTENT_DIR . '/advanced-cache.php';
	10550	+ if ( ! file_exists( $target ) ) {
	10551	+ return self::DROPIN_NONE;
	10552	+ }
	10553	+
	10554	+ $contents = self::read_file( $target );
	10555	+ if ( null === $contents ) {
	10556	+ return self::DROPIN_UNREADABLE;
	10557	+ }
	10558	+
	10559	+ if ( xspeed_has_canonical_dropin_signature( $contents ) ) {
	10560	+ return self::DROPIN_XSPEED;
	10561	+ }
	10562	+
	10563	+ // Nothing in the file means nothing owns it. Kept distinct from
	10564	+ // FOREIGN so the acquisition gate can tell "someone else's cache" from
	10565	+ // "a husk the last plugin left behind". (#391)
	10566	+ if ( '' === trim( $contents ) ) {
	10567	+ return self::DROPIN_ABANDONED;
	10568	+ }
	10569	+
	10570	+ /*
	10571	+ * The other half of the same question, and it cannot be answered from
	10572	+ * the bytes: a file we cannot attribute is a COMPETITOR only while
	10573	+ * some page cache is actually running. With every candidate switched
	10574	+ * off it is abandoned -- a hosting company's own cache, a hand-rolled
	10575	+ * one, or a plugin that was deleted without cleaning up.
	10576	+ *
	10577	+ * Asking the detector rather than re-deriving it here is the point:
	10578	+ * these two answers disagreeing is a split brain with a bad ending --
	10579	+ * acquisition_blocker() opens the gate, install_dropin() then refuses
	10580	+ * on FOREIGN, and toggle() blames the filesystem for a write it never
	10581	+ * attempted. One question, one answer. (#391, #393)
	10582	+ */
	10583	+ if ( class_exists( __NAMESPACE__ . '\\Page_Cache_Detector' ) ) {
	10584	+ $owner = (string) ( Page_Cache_Detector::inspect()['dropin']['owner'] ?? '' );
	10585	+
	10586	+ // Attributable to a named plugin -> somebody's cache, whatever its
	10587	+ // activation state. Only a file NOBODY can be shown to own, with
	10588	+ // nothing running, is abandoned.
	10589	+ if ( Page_Cache_Detector::OWNER_UNKNOWN === $owner
	10590	+ && ! Page_Cache_Detector::another_page_cache_is_active() ) {
	10591	+ return self::DROPIN_ABANDONED;
	10592	+ }
	10593	+ }
	10594	+
	10595	+ return self::DROPIN_FOREIGN;
	10596	+ }
	10597	+
	10598	+ /**
	10599	+ * Why xSpeed must not install its page-cache artifacts right now, or null
	10600	+ * when it may.
	10601	+ *
	10602	+ * This is the single gate in front of every write that touches shared
	10603	+ * state — the drop-in and the WP_CACHE define. Both are single-occupancy:
	10604	+ * whatever is there belongs to exactly one plugin, and taking it silently
	10605	+ * breaks that plugin's caching with no way back.
	10606	+ *
	10607	+ * Returns a user-facing string, so a REST caller can hand it straight to
	10608	+ * the dashboard instead of reporting a bare failure.
	10609	+ */
	10610	+ public static function acquisition_blocker(): ?string {
	10611	+ Page_Cache_Detector::invalidate();
	10612	+ $verdict = Page_Cache_Detector::classify();
	10613	+ $owner = self::dropin_owner();
	10614	+ // The reason we refuse, whether that reason already names a plugin,
	10615	+ // and every other page cache the detector counted anywhere in the
	10616	+ // verdict. See the tail of this method for why all three are needed.
	10617	+ $primary = null;
	10618	+ $primary_names = false;
	10619	+ $named = array();
	10620	+ foreach ( $verdict['blockers'] as $blocker ) {
	10621	+ $code = (string) ( $blocker['code'] ?? '' );
	10622	+ // The shared detector quite correctly reports xSpeed itself as a
	10623	+ // page-cache owner. That is not a competitor to this transaction.
	10624	+ //
	10625	+ // Except when the two disagree about the DROP-IN. The detector
	10626	+ // accepts our marker anywhere in a file's header; this plugin's
	10627	+ // own check requires it to open the header, because only this
	10628	+ // side authorizes overwriting and deleting. A foreign drop-in
	10629	+ // that merely carries our marker further down its header is
	10630	+ // attributed to us by the detector, and skipping it here dropped
	10631	+ // the refusal entirely — the write then failed on the stricter
	10632	+ // check and the user was told to go and fix file permissions.
	10633	+ // Where they disagree, believe the stricter one.
	10634	+ if ( self::PLUGIN_FILE === ( $blocker['plugin'] ?? null ) ) {
	10635	+ $about_dropin = in_array(
	10636	+ $code,
	10637	+ array(
	10638	+ Page_Cache_Detector::BLOCKER_FOREIGN_DROPIN,
	10639	+ Page_Cache_Detector::BLOCKER_UNKNOWN_DROPIN,
	10640	+ ),
	10641	+ true
	10642	+ );
	10643	+ if ( ! $about_dropin || self::DROPIN_XSPEED === $owner ) {
	10644	+ continue;
	10645	+ }
	10646	+ }
	10647	+ if ( Page_Cache_Detector::BLOCKER_WP_CACHE_ORPHANED === $code && self::DROPIN_XSPEED === $owner ) {
	10648	+ continue;
	10649	+ }
	10650	+ /*
	10651	+ * Another plugin's drop-in is no longer a refusal.
	10652	+ *
	10653	+ * It used to be: whoever held advanced-cache.php kept it, and
	10654	+ * enabling was blocked with "deactivate its page cache first".
	10655	+ * That left a user who had asked for our cache with no way to get
	10656	+ * it — on a live site the only exit was deleting a file over SSH,
	10657	+ * and the message could not even say which of its two causes
	10658	+ * applied ("is active OR owns advanced-cache.php").
	10659	+ *
	10660	+ * Turning the page cache on is the instruction to serve pages
	10661	+ * from cache, and that is not possible without this file. So we
	10662	+ * take it, and the dashboard says whose file it is first —
	10663	+ * dropin_disclosure() names the owner, the user confirms, and
	10664	+ * install_dropin() writes ours over the top.
	10665	+ *
	10666	+ * A still-active competitor is deliberately NOT re-added as a
	10667	+ * blocker below: it is caught by `active_page_cache`, which the
	10668	+ * capability rule already downgrades to a note. Two page caches
	10669	+ * installed at once is the user's call to make, not ours to
	10670	+ * refuse — they just told us which one they want serving.
	10671	+ *
	10672	+ * UNREADABLE is the exception and stays a refusal: we cannot name
	10673	+ * what we would destroy, and install_dropin() refuses it too, so
	10674	+ * opening the gate here would only produce a failed write.
	10675	+ */
	10676	+ $about_dropin_owner = in_array(
	10677	+ $code,
	10678	+ array(
	10679	+ Page_Cache_Detector::BLOCKER_FOREIGN_DROPIN,
	10680	+ Page_Cache_Detector::BLOCKER_UNKNOWN_DROPIN,
	10681	+ ),
	10682	+ true
	10683	+ );
	10684	+ if ( $about_dropin_owner && self::DROPIN_UNREADABLE !== $owner ) {
	10685	+ continue;
	10686	+ }
	10687	+ /*
	10688	+ * Capability is not possession. `active_page_cache` and
	10689	+ * `multiple_page_caches` both fire on a plugin that merely CAN
	10690	+ * cache pages — the detector cannot prove a competitor's page
	10691	+ * cache is off, so it counts it. As a warning that is right. As
	10692	+ * a gate it refuses a write that takes nothing from anyone.
	10693	+ *
	10694	+ * This gate guards exactly two files: advanced-cache.php and the
	10695	+ * WP_CACHE define that loads it. A plugin that does not hold the
	10696	+ * drop-in has nothing here for us to overwrite, and one that does
	10697	+ * is already refused by `foreign_dropin` / `unknown_dropin` a few
	10698	+ * lines up. So when the field is ours or empty, an active
	10699	+ * competitor is a note, not a refusal.
	10700	+ *
	10701	+ * QA found this on a live OpenLiteSpeed site keeping LiteSpeed
	10702	+ * Cache for images and CDN with its page cache off, while xSpeed
	10703	+ * served the pages. One click of the off switch and it could not
	10704	+ * be turned back on: the only way out was deactivating LiteSpeed
	10705	+ * entirely, and the message told them to "deactivate its page
	10706	+ * cache" — which they already had.
	10707	+ */
	10708	+ $about_capability = in_array(
	10709	+ $code,
	10710	+ array(
	10711	+ Page_Cache_Detector::BLOCKER_ACTIVE_PAGE_CACHE,
	10712	+ Page_Cache_Detector::BLOCKER_MULTIPLE_PAGE_CACHES,
	10713	+ ),
	10714	+ true
	10715	+ );
	10716	+ /*
	10717	+ * FOREIGN belongs in this list now, and it is the whole point.
	10718	+ *
	10719	+ * The rule is still "capability is not possession": these two
	10720	+ * blockers fire on any plugin that CAN cache pages, which the
	10721	+ * detector cannot prove is switched off. What changed is that a
	10722	+ * competitor holding the drop-in no longer stops us either — we
	10723	+ * take the file, having said whose it is. So there is nothing
	10724	+ * left for a merely-installed competitor to protect, and keeping
	10725	+ * the refusal here would put back the dead end by another route:
	10726	+ * "another page cache is active" on a site where the user has
	10727	+ * just told us, by name, which cache they want serving.
	10728	+ *
	10729	+ * UNREADABLE is deliberately still absent — that one refuses.
	10730	+ */
	10731	+ if ( $about_capability
	10732	+ && in_array( $owner, array( self::DROPIN_XSPEED, self::DROPIN_NONE, self::DROPIN_FOREIGN, self::DROPIN_ABANDONED ), true ) ) {
	10733	+ continue;
	10734	+ }
	10735	+ if ( Page_Cache_Detector::BLOCKER_MULTIPLE_PAGE_CACHES === $code ) {
	10736	+ $others = self::other_page_cache_names( $blocker );
	10737	+ if ( array() === $others ) {
	10738	+ // We were the only owner counted — nothing to refuse —
	10739	+ // unless the list is missing entirely, which is an older
	10740	+ // detector copy we still must not talk past.
	10741	+ if ( null === $primary && array() === (array) ( $blocker['plugins'] ?? array() ) ) {
	10742	+ $primary = self::ownership_blocker_message( '', '' );
	10743	+ }
	10744	+ continue;
	10745	+ }
	10746	+ $named = array_values( array_unique( array_merge( $named, $others ) ) );
	10747	+ if ( null === $primary ) {
	10748	+ $primary = self::multiple_page_caches_message( $others );
	10749	+ $primary_names = true;
	10750	+ }
	10751	+ continue;
	10752	+ }
	10753	+ if ( null === $primary ) {
	10754	+ $label = (string) ( $blocker['label'] ?? '' );
	10755	+ $primary = self::ownership_blocker_message( $code, $label );
	10756	+ $primary_names = '' !== $label;
	10757	+ }
	10758	+ }
	10759	+
	10760	+ if ( null === $primary ) {
	10761	+ return null;
	10762	+ }
	10763	+ /*
	10764	+ * The first blocker decides WHY we refuse; it does not always know
	10765	+ * WHO. The detector can only attribute a drop-in it recognises, and
	10766	+ * an unrecognised one produces "its owner cannot be proved" — the
	10767	+ * sentence a W3 Total Cache site used to get while a later blocker in
	10768	+ * the same verdict was holding the name "W3 Total Cache".
	10769	+ *
	10770	+ * So keep the reason and add the names, rather than swapping one for
	10771	+ * the other: the plugin the user must deal with is not necessarily
	10772	+ * the owner of the file we could not identify, and promoting the
	10773	+ * named blocker would have told them to deactivate a plugin that is
	10774	+ * not what is in their way.
	10775	+ */
	10776	+ if ( $primary_names || array() === $named ) {
	10777	+ return $primary;
	10778	+ }
	10779	+ if ( 1 === count( $named ) ) {
	10780	+ return sprintf(
	10781	+ /* translators: 1: the refusal reason, 2: a page-caching plugin's name. */
	10782	+ __( '%1$s %2$s is also active on this site — deactivate its page cache before enabling xSpeed.', 'xspeed' ),
	10783	+ $primary,
	10784	+ $named[0]
	10785	+ );
	10786	+ }
	10787	+ return sprintf(
	10788	+ /* translators: 1: the refusal reason, 2: comma-separated page-caching plugin names. */
	10789	+ __( '%1$s These page caches are also active on this site: %2$s. Deactivate them before enabling xSpeed.', 'xspeed' ),
	10790	+ $primary,
	10791	+ implode( ', ', $named )
	10792	+ );
	10793	+ }
	10794	+
	10795	+ /** How xSpeed's own plugin file appears in the detector's catalog. */
	10796	+ private const PLUGIN_FILE = 'xspeed/xspeed.php';
	10797	+
	10798	+ /**
	10799	+ * Name the OTHER page caches behind a `multiple_page_caches` refusal.
	10800	+ *
	10801	+ * This blocker has no single owner, so the detector leaves `plugin` and
	10802	+ * `label` null and hands over the full list instead. Left unhandled it
	10803	+ * fell through to the anonymous fallback sentence — and it is the blocker
	10804	+ * an ordinary site hits most: xSpeed counts toward "multiple", so the
	10805	+ * count reaches two the moment one other page-cache plugin is activated,
	10806	+ * even one that has not written a drop-in. A site running our cache that
	10807	+ * activated LiteSpeed could not re-enable it and was told only that "the
	10808	+ * page-cache field is occupied".
	10809	+ *
	10810	+ * Returns an empty list when xSpeed was the only owner counted, or when
	10811	+ * an older detector copy sent no list at all — the caller distinguishes
	10812	+ * the two by looking at `plugins`.
	10813	+ *
	10814	+ * @param array<string,mixed> $blocker One entry from Detector::classify().
	10815	+ * @return string[]
	10816	+ */
	10817	+ private static function other_page_cache_names( array $blocker ): array {
	10818	+ $plugins = array_values( (array) ( $blocker['plugins'] ?? array() ) );
	10819	+ $labels = array_values( (array) ( $blocker['labels'] ?? array() ) );
	10820	+
	10821	+ $others = array();
	10822	+ foreach ( $plugins as $i => $plugin ) {
	10823	+ if ( self::PLUGIN_FILE === $plugin ) {
	10824	+ continue;
	10825	+ }
	10826	+ $others[] = isset( $labels[ $i ] ) && '' !== (string) $labels[ $i ]
	10827	+ ? (string) $labels[ $i ]
	10828	+ : (string) $plugin;
	10829	+ }
	10830	+ return array_values( array_unique( $others ) );
	10831	+ }
	10832	+
	10833	+ /**
	10834	+ * The refusal sentence for a `multiple_page_caches` blocker.
	10835	+ *
	10836	+ * @param string[] $others Page caches other than xSpeed. Never empty.
	10837	+ */
	10838	+ private static function multiple_page_caches_message( array $others ): string {
	10839	+ if ( 1 === count( $others ) ) {
	10840	+ return self::ownership_blocker_message( Page_Cache_Detector::BLOCKER_ACTIVE_PAGE_CACHE, $others[0] );
	10841	+ }
	10842	+ return sprintf(
	10843	+ /* translators: %s: comma-separated list of page-caching plugin names. */
	10844	+ __( 'More than one page cache is active on this site (%s). Turn off the other page caches before enabling xSpeed.', 'xspeed' ),
	10845	+ implode( ', ', $others )
	10846	+ );
	10847	+ }
	10848	+
	10849	+ private static function ownership_blocker_message( string $code, string $label ): string {
	10850	+ // The plugin can stay active. Only its page cache is in the way, so
	10851	+ // say that rather than "deactivate it". (#653)
	10852	+ if ( Page_Cache_Detector::BLOCKER_PAGE_CACHE_SWITCHED_ON === $code && '' !== $label ) {
	10853	+ return sprintf(
	10854	+ /* translators: %s: a page-caching plugin's name, e.g. LiteSpeed Cache. */
	10855	+ __( "%s's page cache is on. Turn it off in that plugin's settings before enabling xSpeed's page cache. The plugin can stay active.", 'xspeed' ),
	10856	+ $label
	10857	+ );
	10858	+ }
	10859	+ if ( '' !== $label ) {
	10860	+ return sprintf( __( '%s is active or owns advanced-cache.php. Deactivate its page cache before enabling xSpeed.', 'xspeed' ), $label );
	10861	+ }
	10862	+ $messages = array(
	10863	+ 'wp_cache_orphaned' => __( 'WP_CACHE is true but no page-cache drop-in owner can be proved. xSpeed will not claim it.', 'xspeed' ),
	10864	+ 'wp_cache_duplicate' => __( 'wp-config.php defines WP_CACHE more than once. Remove the duplicate before enabling the cache.', 'xspeed' ),
	10865	+ 'wp_cache_dynamic' => __( 'WP_CACHE is set from an expression in wp-config.php. xSpeed will not rewrite it.', 'xspeed' ),
	10866	+ 'wp_cache_conditional' => __( 'WP_CACHE is defined inside a conditional in wp-config.php, so xSpeed cannot tell what it will be. Move it to a plain define before enabling the cache.', 'xspeed' ),
	10867	+ 'wp_config_unreadable' => __( 'wp-config.php cannot be read, so xSpeed cannot safely change page-cache ownership.', 'xspeed' ),
	10868	+ 'unknown_dropin' => __( 'advanced-cache.php is occupied but its owner cannot be proved. xSpeed will not replace it.', 'xspeed' ),
	10869	+ 'unreadable_dropin' => __( 'advanced-cache.php cannot be read, so xSpeed cannot prove its owner.', 'xspeed' ),
	10870	+ );
	10871	+ return $messages[ $code ] ?? __( 'The page-cache field is occupied or cannot be verified. xSpeed will not change it.', 'xspeed' );
	10872	+ }
	10873	+
	10874	+ /**
	10875	+ * How WP_CACHE is written in wp-config.php, as opposed to what it
	10876	+ * evaluates to at runtime.
	10877	+ *
	10878	+ * The literal is what matters to a writer: a value behind an expression,
	10879	+ * or two competing defines, cannot be rewritten by a regex without
	10880	+ * guessing — and a wrong guess silently disables page caching (ours or
	10881	+ * someone else's) with no error anywhere.
	10882	+ *
	10883	+ * @return string undefined | true | false | duplicate | dynamic | conditional | unreadable
	10884	+ */
	10885	+ public static function wp_cache_define_state(): string {
	10886	+ $path = self::wp_config_path();
	10887	+ if ( '' === $path ) {
	10888	+ return 'unreadable';
	10889	+ }
	10890	+
	10891	+ $config = self::read_file( $path );
	10892	+ if ( null === $config ) {
	10893	+ return 'unreadable';
	10894	+ }
	10895	+
	10896	+ require_once XSPEED_DIR . 'includes/wp-cache-constant.php';
	10897	+ $parsed = \xspeed_parse_wp_cache_defines( $config );
	10898	+ return $parsed['state'];
	10899	+ }
	10900	+
	10901	+ /**
	10902	+ * Classify the captured right-hand side of a WP_CACHE define.
	10903	+ *
	10904	+ * Hosts and older tutorials write the value several ways —
	10905	+ * `1`, `'1'`, `TRUE` — and all of them are literals a rewrite can safely
	10906	+ * replace. Only a value we cannot evaluate by looking at it (a variable, a
	10907	+ * function call, a ternary) counts as dynamic, because that is the case
	10908	+ * where rewriting means guessing.
	10909	+ *
	10910	+ * @return string true | false | dynamic
	10911	+ */
	10912	+ private static function classify_wp_cache_literal( string $raw ): string {
	10913	+ $literal = strtolower( trim( $raw ) );
	10914	+ $literal = trim( $literal, "'\"" );
	10915	+
	10916	+ if ( in_array( $literal, array( 'true', '1' ), true ) ) {
	10917	+ return 'true';
	10918	+ }
	10919	+ if ( in_array( $literal, array( 'false', '0', '', 'null' ), true ) ) {
	10920	+ return 'false';
	10921	+ }
	10922	+ return 'dynamic';
	10923	+ }
	10924	+
	10925	+ /**
	10926	+ * Read a file for an ownership decision. Null on any failure — callers
	10927	+ * treat null as "unknown", never as "empty", because an empty string
	10928	+ * would read as "no marker found" and license an overwrite.
	10929	+ */
	10930	+ private static function read_file( string $path ): ?string {
	10931	+ if ( ! is_readable( $path ) ) {
	10932	+ return null;
	10933	+ }
	10934	+ // phpcs:ignore WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents -- Ownership check on a local file; WP_Filesystem would need credentials we must not prompt for here.
	10935	+ $contents = @file_get_contents( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- A failed read is a valid answer ("unknown"), not an error to surface.
	10936	+ return is_string( $contents ) ? $contents : null;
	10937	+ }
	10938	+
1886	10939	public static function install_dropin() {
1887	10940	$source = XSPEED_DIR . 'includes/advanced-cache.php';
1888	10941	$target = WP_CONTENT_DIR . '/advanced-cache.php';
1889	10942	if ( ! file_exists( $source ) ) {
		@@ -1889,8 +10942,26 @@
1889	10942	if ( ! file_exists( $source ) ) {
1890	10943	return false;
1891	10944	}
1892	10945
	10946	+ /*
	10947	+ * A drop-in we cannot READ is the one thing still refused here. Not
	10948	+ * because of who owns it — we no longer refuse on ownership — but
	10949	+ * because an unreadable file is usually a permissions problem, and
	10950	+ * writing over it would fail anyway or destroy something we were
	10951	+ * never able to look at.
	10952	+ *
	10953	+ * Everything else is ours to take. Enabling the page cache IS the
	10954	+ * user's instruction to serve the cache, and serving it means holding
	10955	+ * advanced-cache.php; the dashboard says whose file it is replacing
	10956	+ * before the click (Page_Cache_Detector::dropin_disclosure()), so the
	10957	+ * takeover is consented rather than silent.
	10958	+ */
	10959	+ $owner = self::dropin_owner();
	10960	+ if ( self::DROPIN_UNREADABLE === $owner ) {
	10961	+ return false;
	10962	+ }
	10963	+
1893	10964	global $wp_filesystem;
1894	10965	if ( ! function_exists( 'WP_Filesystem' ) ) {
1895	10966	require_once ABSPATH . 'wp-admin/includes/file.php';
1896	10967	}
		@@ -1914,38 +10985,144 @@
1914	10985	str_replace( "'", "\\'", self::hits_log_path() ),
1915	10986	$source_contents
1916	10987	);
1917	10988
	10989	+ // Bake the cookie + user-agent exclusion rules in too. The drop-in
	10990	+ // runs before WordPress loads, so it cannot read the settings — and
	10991	+ // without them it served the shared anonymous page to any visitor
	10992	+ // PHP had not yet seen (a first-time cart visitor, a bypassed bot).
	10993	+ // The generic bypass cookie only covers repeat visitors; these two
	10994	+ // regexes are what make the FIRST request correct.
	10995	+ //
	10996	+ // Both are already fully escaped by Server_Rules, and each is
	10997	+ // embedded as a single-quoted PHP literal, so a settings value can
	10998	+ // neither break the drop-in's syntax nor execute.
	10999	+ $cache_opts = Settings_Manager::get( 'cache' );
	11000	+ $cookie_rule = Server_Rules::cookie_rule(
	11001	+ is_array( $cache_opts['excluded_cookies'] ?? null ) ? $cache_opts['excluded_cookies'] : array()
	11002	+ );
	11003	+ $ua_rule = Server_Rules::user_agent_rule(
	11004	+ is_array( $cache_opts['bypass_user_agents'] ?? null ) ? $cache_opts['bypass_user_agents'] : array()
	11005	+ );
	11006	+
	11007	+ $source_contents = str_replace(
	11008	+ '@@XSPEED_COOKIE_RE@@',
	11009	+ str_replace( "'", "\\'", $cookie_rule['regex'] ),
	11010	+ $source_contents
	11011	+ );
	11012	+ $source_contents = str_replace(
	11013	+ '@@XSPEED_UA_RE@@',
	11014	+ str_replace( "'", "\\'", $ua_rule['regex'] ),
	11015	+ $source_contents
	11016	+ );
	11017	+ // Which user agents must not count toward the hit ratio. Built here
	11018	+ // because `xspeed_self_user_agents` is a filter the drop-in cannot
	11019	+ // call. A renamed warmer is caught by Self_Traffic::HEADER instead.
	11020	+ $source_contents = str_replace(
	11021	+ '@@XSPEED_HIT_EXCLUDE_RE@@',
	11022	+ str_replace( "'", "\\'", Hit_Counter::excluded_ua_regex() ),
	11023	+ $source_contents
	11024	+ );
	11025	+
	11026	+ /*
	11027	+ * Ours or absent — the ownership gate at the top of this method ruled
	11028	+ * out everything else. The old code path that moved a foreign drop-in
	11029	+ * into uploads/xspeed-backups and wrote ours on top is gone: it
	11030	+ * disabled the other plugin's page cache the moment an xSpeed install
	11031	+ * ran, with nothing in its own UI to explain why.
	11032	+ */
	11033	+
	11034	+ // Bake the configured cache lifetime in. The drop-in runs before
	11035	+ // WordPress loads, so it cannot read the option — it previously fell
	11036	+ // back to a hardcoded 86400 for every ordinary page, because
	11037	+ // write_meta() only emits a `ttl` sidecar when the value DIFFERS from
	11038	+ // the page default. That made the admin's "1 to 720 hours" control a
	11039	+ // no-op at the layer that actually answers the request: 12h served
	11040	+ // stale for up to 2x the configured lifetime, and 168h lost the fast
	11041	+ // path for 6 of every 7 days (issue #240).
	11042	+ //
	11043	+ // This is re-baked on every cache settings save (see CacheModule::boot),
	11044	+ // exactly like the cookie / user-agent rules above.
	11045	+ $expiry_hours = isset( $cache_opts['cache_expiry'] ) ? (int) $cache_opts['cache_expiry'] : 24;
	11046	+ if ( $expiry_hours < 1 || $expiry_hours > 720 ) {
	11047	+ $expiry_hours = 24;
	11048	+ }
	11049	+ $source_contents = str_replace(
	11050	+ '@@XSPEED_DEFAULT_TTL@@',
	11051	+ (string) ( $expiry_hours * HOUR_IN_SECONDS ),
	11052	+ $source_contents
	11053	+ );
	11054	+
	11055	+ // Bake the site-wide edge answer in. Resolved in a `bake` context, so
	11056	+ // nothing per-page and nothing a request header vouched for can reach
	11057	+ // it: a bake runs once, in an admin or CLI request, and answers for
	11058	+ // every page on the site. A page that disagrees gets a sidecar
	11059	+ // instead — see per_entry_edge_headers().
	11060	+ //
	11061	+ // Re-baked on every cache settings save (see CacheModule::boot),
	11062	+ // exactly like the cookie, user-agent and lifetime rules above.
	11063	+ $source_contents = str_replace(
	11064	+ "'@@XSPEED_EDGE_HEADERS@@'",
	11065	+ self::edge_headers_literal( self::edge_headers_for( 'HIT', 'bake' ) ),
	11066	+ $source_contents
	11067	+ );
	11068	+
	11069	+ // And the answer for the same HIT served for a URL with an ignored
	11070	+ // param in it, which the drop-in sends instead of the one above. An
	11071	+ // empty array means the two agree. See query_variant_edge_headers().
	11072	+ $source_contents = str_replace(
	11073	+ "'@@XSPEED_EDGE_QUERY_HOLD@@'",
	11074	+ self::edge_headers_literal( self::query_variant_edge_headers() ),
	11075	+ $source_contents
	11076	+ );
	11077	+
1918	11078	if ( file_exists( $target ) ) {
1919	11079	$existing = $wp_filesystem->get_contents( $target );
1920		- $is_xspeed = is_string( $existing ) && false !== strpos( $existing, 'XSPEED_DROPIN' );
	11080	+ if ( is_string( $existing ) && $existing === $source_contents ) {
	11081	+ return true;
	11082	+ }
	11083	+ }
1921	11084
1922		- if ( $is_xspeed ) {
1923		- if ( $existing === $source_contents ) {
1924		- return true;
1925		- }
1926		- return (bool) $wp_filesystem->put_contents( $target, $source_contents, FS_CHMOD_FILE );
1927		- }
	11085	+ $written = (bool) $wp_filesystem->put_contents( $target, $source_contents, FS_CHMOD_FILE );
	11086	+ if ( $written ) {
	11087	+ self::forget_compiled_dropin( $target );
	11088	+ }
	11089	+ return $written;
	11090	+ }
1928	11091
1929		- // Foreign drop-in (e.g. left over from another cache plugin) — back it up
1930		- // before overwriting so the user can recover if needed. Uploads dir
1931		- // (not wp-content root) keeps the backup out of WordPress's reserved
1932		- // drop-in location.
1933		- $upload = wp_upload_dir( null, false );
1934		- $basedir = isset( $upload['basedir'] ) ? trailingslashit( $upload['basedir'] ) . 'xspeed-backups' : false;
1935		- if ( $basedir ) {
1936		- if ( ! file_exists( $basedir ) ) {
1937		- wp_mkdir_p( $basedir );
1938		- self::write_silence( $basedir );
1939		- }
1940		- $backup = $basedir . '/advanced-cache.foreign-' . gmdate( 'Ymd-His' ) . '.php.bak';
1941		- $wp_filesystem->move( $target, $backup, true );
1942		- } else {
1943		- $wp_filesystem->delete( $target );
	11092	+ /**
	11093	+ * Callable that drops a script's compiled copy. Replaced by tests only;
	11094	+ * opcache_invalidate() is a PHP internal that cannot be stubbed.
	11095	+ *
	11096	+ * @var callable|null
	11097	+ */
	11098	+ private static $opcache_invalidate = null;
	11099	+
	11100	+ /**
	11101	+ * Make PHP compile the new drop-in on the next request.
	11102	+ *
	11103	+ * opcache keeps the compiled drop-in and checks the file's timestamp at
	11104	+ * most every `opcache.revalidate_freq` seconds (60 on lenzora.site), or
	11105	+ * never with `validate_timestamps` off. So a re-bake, such as the one
	11106	+ * that follows a change to "CDN or proxy in front", kept serving the old
	11107	+ * edge headers for up to a minute, or until PHP restarted.
	11108	+ *
	11109	+ * This reaches the opcache of the PHP process doing the write, which is
	11110	+ * the web server's own when the bake runs in a page or REST request. A
	11111	+ * WP-CLI bake has its own opcache, so the web server still waits for its
	11112	+ * next timestamp check there.
	11113	+ *
	11114	+ * @param string $target Absolute path of the drop-in just written.
	11115	+ */
	11116	+ private static function forget_compiled_dropin( string $target ): void {
	11117	+ $invalidate = self::$opcache_invalidate;
	11118	+ if ( null === $invalidate ) {
	11119	+ if ( ! function_exists( 'opcache_invalidate' ) ) {
	11120	+ return;
1944	11121	}
	11122	+ $invalidate = 'opcache_invalidate';
1945	11123	}
1946		-
1947		- return (bool) $wp_filesystem->put_contents( $target, $source_contents, FS_CHMOD_FILE );
	11124	+ @call_user_func( $invalidate, $target, true ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- opcache may be disabled or restricted (opcache.restrict_api); nothing to do either way.
1948	11125	}
1949	11126
1950	11127	public static function remove_dropin() {
1951	11128	$target = WP_CONTENT_DIR . '/advanced-cache.php';
		@@ -1962,61 +11139,374 @@
1962	11139	return;
1963	11140	}
1964	11141
1965	11142	$contents = $wp_filesystem->get_contents( $target );
1966		- if ( is_string( $contents ) && false !== strpos( $contents, 'XSPEED_DROPIN' ) ) {
	11143	+ if ( is_string( $contents ) && xspeed_has_canonical_dropin_signature( $contents ) ) {
1967	11144	wp_delete_file( $target );
1968	11145	}
1969	11146	}
1970	11147
	11148	+ /**
	11149	+ * Where wp-config.php actually is.
	11150	+ *
	11151	+ * WordPress core supports the file one directory ABOVE ABSPATH, and
	11152	+ * plenty of installs use that layout. This used to look only in ABSPATH
	11153	+ * and bail, so on those sites the constant could never be written — while
	11154	+ * Health, which did fall back to the parent, reported the file writable
	11155	+ * and told the user to toggle the cache off and on. The advice could
	11156	+ * never work, and its fallback hint ("another plugin left WP_CACHE false
	11157	+ * behind") was wrong too: there was no define at all. (#19, QA on #174)
	11158	+ *
	11159	+ * Returns '' when no wp-config.php can be found in either location.
	11160	+ */
	11161	+ public static function wp_config_path(): string {
	11162	+ $candidates = array( ABSPATH . 'wp-config.php', dirname( ABSPATH ) . '/wp-config.php' );
	11163	+ foreach ( $candidates as $path ) {
	11164	+ if ( file_exists( $path ) ) {
	11165	+ return $path;
	11166	+ }
	11167	+ }
	11168	+ return '';
	11169	+ }
	11170	+
	11171	+ /**
	11172	+ * Can we actually write the constant right now?
	11173	+ *
	11174	+ * This is the single oracle for that question — Health asks THIS rather
	11175	+ * than running its own `wp_is_writable()` test, so the message a user
	11176	+ * reads can never disagree with what the plugin will do. The two differed
	11177	+ * in both directions: on the path (above) and on the test itself, since
	11178	+ * an FTP/SSH WP_Filesystem transport can refuse a file that
	11179	+ * `wp_is_writable()` reports as writable. (#19, QA on #174)
	11180	+ */
	11181	+ public static function can_write_wp_config(): bool {
	11182	+ $wp_config = self::wp_config_path();
	11183	+ if ( '' === $wp_config ) {
	11184	+ return false;
	11185	+ }
	11186	+
	11187	+ global $wp_filesystem;
	11188	+ if ( ! function_exists( 'WP_Filesystem' ) ) {
	11189	+ require_once ABSPATH . 'wp-admin/includes/file.php';
	11190	+ }
	11191	+ WP_Filesystem();
	11192	+ return (bool) ( $wp_filesystem && $wp_filesystem->is_writable( $wp_config ) );
	11193	+ }
	11194	+
1971	11195	public static function set_wp_cache_constant( $enable ) {
1972		- $wp_config = ABSPATH . 'wp-config.php';
1973		- if ( ! file_exists( $wp_config ) ) {
	11196	+ $wp_config = self::wp_config_path();
	11197	+ if ( '' === $wp_config ) {
1974	11198	return false;
1975	11199	}
1976	11200
	11201	+ /*
	11202	+ * WP_CACHE belongs to whoever owns the drop-in — it is the switch that
	11203	+ * makes core load that one file. Editing it while someone else's
	11204	+ * drop-in is installed either turns THEIR cache on or off; either way
	11205	+ * it is a write to another plugin's state. So: no ownership, no edit.
	11206	+ */
	11207	+ $owner = self::dropin_owner();
	11208	+ if ( self::DROPIN_FOREIGN === $owner || self::DROPIN_UNREADABLE === $owner ) {
	11209	+ return false;
	11210	+ }
	11211	+
	11212	+ $state = self::wp_cache_define_state();
	11213	+ if ( 'duplicate' === $state || 'dynamic' === $state ) {
	11214	+ // Two competing defines, or a value behind an expression. A regex
	11215	+ // rewrite here is a guess, and a wrong guess silently kills page
	11216	+ // caching with no error anywhere.
	11217	+ return false;
	11218	+ }
1977	11219	global $wp_filesystem;
1978	11220	if ( ! function_exists( 'WP_Filesystem' ) ) {
1979	11221	require_once ABSPATH . 'wp-admin/includes/file.php';
1980	11222	}
1981	11223	WP_Filesystem();
1982		- if ( ! $wp_filesystem || ! $wp_filesystem->is_writable( $wp_config ) ) {
	11224	+ if ( ! $wp_filesystem ) {
1983	11225	return false;
1984	11226	}
1985	11227
1986	11228	$config = $wp_filesystem->get_contents( $wp_config );
	11229	+ if ( ! is_string( $config ) ) {
	11230	+ return false;
	11231	+ }
	11232	+ require_once XSPEED_DIR . 'includes/wp-cache-constant.php';
	11233	+ $marker = $enable ? self::wp_cache_receipt() : '';
	11234	+ $updated = xspeed_rewrite_wp_cache_define( $config, (bool) $enable, $marker );
	11235	+ if ( ! is_string( $updated ) ) {
	11236	+ return false;
	11237	+ }
1987	11238
1988		- if ( $enable ) {
1989		- if ( strpos( $config, "define( 'WP_CACHE'" ) !== false || strpos( $config, "define('WP_CACHE'" ) !== false ) {
1990		- return true;
	11239	+ /*
	11240	+ * Removing a WP_CACHE line we cannot prove we wrote is somebody else's
	11241	+ * configuration, so a disable needs either our drop-in or our receipt.
	11242	+ *
	11243	+ * The test is on the REWRITE, not on the request: it used to run
	11244	+ * before the rewrite and refuse a disable that had nothing to remove.
	11245	+ * An ordinary site with no drop-in and no define — every fresh
	11246	+ * install — therefore failed to turn page caching off, so the
	11247	+ * onboarding wizard reported "setup needs attention" to every user who
	11248	+ * declined it and Migration reported the cache import as failed.
	11249	+ */
	11250	+ if ( ! $enable && $updated !== $config
	11251	+ && self::DROPIN_XSPEED !== $owner
	11252	+ && ! self::wp_cache_receipt_matches_source( $config ) ) {
	11253	+ return false;
	11254	+ }
	11255	+
	11256	+ /*
	11257	+ * Nothing to write. auto_heal() runs the whole enable transaction on
	11258	+ * every admin_init, so without this every wp-admin request rewrote
	11259	+ * wp-config.php with byte-identical content: pointless disk churn
	11260	+ * that trips host file-integrity monitors and widens the window for
	11261	+ * a concurrent write on a busy admin.
	11262	+ *
	11263	+ * It is also what makes a correct WP_CACHE on a read-only
	11264	+ * wp-config.php succeed. A managed host that ships the file
	11265	+ * unwritable, on a site where the user already pasted the define,
	11266	+ * is in the state we wanted — the writability test below is about
	11267	+ * whether we can CHANGE the file, and there is nothing to change.
	11268	+ */
	11269	+ if ( $updated === $config ) {
	11270	+ if ( ! $enable ) {
	11271	+ // Our line is not in the file, so the receipt that proved we
	11272	+ // wrote it is stale — drop it on the same terms as a real
	11273	+ // removal, or uninstall keeps a claim on nothing.
	11274	+ delete_option( 'xspeed_page_cache_ownership_receipt' );
1991	11275	}
1992		- $config = preg_replace( '/(<\?php)/', "$1\ndefine( 'WP_CACHE', true );", $config, 1 );
1993		- } else {
1994		- $config = preg_replace( "/define\\(\\s*['\"]WP_CACHE['\"]\\s*,\\s*true\\s*\\);\\s*\\n?/", '', $config );
	11276	+ return true;
1995	11277	}
1996	11278
1997		- return (bool) $wp_filesystem->put_contents( $wp_config, $config, FS_CHMOD_FILE );
	11279	+ if ( ! $wp_filesystem->is_writable( $wp_config ) ) {
	11280	+ return false;
	11281	+ }
	11282	+ $written = (bool) $wp_filesystem->put_contents( $wp_config, $updated, FS_CHMOD_FILE );
	11283	+ if ( $written && ! $enable ) {
	11284	+ delete_option( 'xspeed_page_cache_ownership_receipt' );
	11285	+ }
	11286	+ return $written;
1998	11287	}
1999	11288
	11289	+ private static function wp_cache_receipt(): string {
	11290	+ $receipt = get_option( 'xspeed_page_cache_ownership_receipt', '' );
	11291	+ if ( is_string( $receipt ) && preg_match( '/^[a-f0-9]{32}$/', $receipt ) ) {
	11292	+ return $receipt;
	11293	+ }
	11294	+ $receipt = substr( hash( 'sha256', XSPEED_DIR . microtime( true ) . mt_rand() ), 0, 32 );
	11295	+ update_option( 'xspeed_page_cache_ownership_receipt', $receipt, false );
	11296	+ return $receipt;
	11297	+ }
	11298	+
	11299	+ /**
	11300	+ * Is the WP_CACHE line in wp-config.php ours to REMOVE?
	11301	+ *
	11302	+ * Two different questions live here and only one of them matters. "Did we
	11303	+ * write it" is answered by our drop-in on disk or by our receipt comment
	11304	+ * beside the define. "Is it ours to remove" also asks what the line does
	11305	+ * NOW — and once a competitor owns advanced-cache.php, a line we wrote
	11306	+ * ourselves is the switch that loads THEIR drop-in. They had no reason to
	11307	+ * touch an already-true define, so our receipt is still sitting on it.
	11308	+ * Removing it there would stop their live page cache.
	11309	+ *
	11310	+ * So a foreign or unreadable owner is never ours to remove, whatever the
	11311	+ * receipt says, and the caller treats that as a reason to leave the line
	11312	+ * and get on with disabling our own cache — not as a reason to refuse.
	11313	+ */
	11314	+ private static function wp_cache_define_is_ours_to_remove( string $owner ): bool {
	11315	+ if ( self::DROPIN_FOREIGN === $owner || self::DROPIN_UNREADABLE === $owner ) {
	11316	+ return false;
	11317	+ }
	11318	+ if ( self::DROPIN_XSPEED === $owner ) {
	11319	+ return true;
	11320	+ }
	11321	+ $path = self::wp_config_path();
	11322	+ if ( '' === $path ) {
	11323	+ return false;
	11324	+ }
	11325	+ $config = self::read_file( $path );
	11326	+ return is_string( $config ) && self::wp_cache_receipt_matches_source( $config );
	11327	+ }
	11328	+
	11329	+ private static function wp_cache_receipt_matches_source( string $source ): bool {
	11330	+ $receipt = get_option( 'xspeed_page_cache_ownership_receipt', '' );
	11331	+ require_once XSPEED_DIR . 'includes/wp-cache-constant.php';
	11332	+ return xspeed_wp_cache_receipt_matches( $source, $receipt );
	11333	+ }
	11334	+
	11335	+ /**
	11336	+ * Admin-bar purge menu — a parent node plus one child per visible cache
	11337	+ * type (LiteSpeed-style), instead of a single "Purge All" link. Each
	11338	+ * child posts to the same admin-post handler with its type slug. The
	11339	+ * per-type items only appear for active/licensed modules; "Purge All"
	11340	+ * always shows and always sweeps everything. (FBS-83114)
	11341	+ *
	11342	+ * The parent node links to the settings page rather than a purge URL —
	11343	+ * clicking the top-level item used to wipe the whole cache instantly with
	11344	+ * no confirmation, which is far too destructive for a stray click. Purging
	11345	+ * stays available (and explicit) through the child items. (FBS-84068)
	11346	+ */
2000	11347	public function admin_bar_purge( $wp_admin_bar ) {
2001	11348	if ( ! current_user_can( 'manage_options' ) ) {
2002	11349	return;
2003	11350	}
	11351	+
2004	11352	$wp_admin_bar->add_node(
2005	11353	array(
2006	11354	'id' => 'xspeed-purge',
2007		- 'title' => __( 'Purge xSpeed Cache', 'xspeed' ),
2008		- 'href' => wp_nonce_url( admin_url( 'admin-post.php?action=xspeed_purge' ), 'xspeed_purge' ),
	11355	+ 'title' => __( 'xSpeed Cache', 'xspeed' ),
	11356	+ 'href' => admin_url( 'admin.php?page=' . Admin::PAGE_SLUG ),
2009	11357	)
2010	11358	);
	11359	+
	11360	+ // Settings first, then the two whole-errand actions (Purge All,
	11361	+ // Purge this URL), then the per-type items. The order is the one WP
	11362	+ // Rocket uses, and it front-loads what people open this menu for:
	11363	+ // nobody reaches for "Purge Object Cache" as often as they reach for
	11364	+ // the page they are looking at.
	11365	+ $wp_admin_bar->add_node(
	11366	+ array(
	11367	+ 'id' => 'xspeed-purge-settings',
	11368	+ 'parent' => 'xspeed-purge',
	11369	+ 'title' => esc_html__( 'Settings', 'xspeed' ),
	11370	+ 'href' => admin_url( 'admin.php?page=' . Admin::PAGE_SLUG ),
	11371	+ )
	11372	+ );
	11373	+
	11374	+ $types = self::purge_types();
	11375	+
	11376	+ // 'all' is rendered out of band so the single-URL item can sit
	11377	+ // directly under it. A filter that reorders or drops it is honoured:
	11378	+ // the loop below skips whatever was emitted here.
	11379	+ $emitted = array();
	11380	+ if ( ! empty( $types['all']['visible'] ) ) {
	11381	+ $wp_admin_bar->add_node(
	11382	+ array(
	11383	+ 'id' => 'xspeed-purge-all',
	11384	+ 'parent' => 'xspeed-purge',
	11385	+ 'title' => esc_html( $types['all']['label'] ),
	11386	+ 'href' => self::purge_type_url( 'all' ),
	11387	+ )
	11388	+ );
	11389	+ $emitted['all'] = true;
	11390	+ }
	11391	+
	11392	+ // Only when the current screen is about one thing — a front-end view,
	11393	+ // or a published post's edit screen. On a list table or a settings
	11394	+ // page there is nothing for "this" to mean, so the item stays hidden
	11395	+ // rather than silently targeting the dashboard. Purge_Ui decides both
	11396	+ // the label and the scope, which differ between the two contexts.
	11397	+ $context = Purge_Ui::context_node();
	11398	+ if ( null !== $context ) {
	11399	+ $wp_admin_bar->add_node(
	11400	+ array(
	11401	+ 'id' => 'xspeed-purge-this-url',
	11402	+ 'parent' => 'xspeed-purge',
	11403	+ 'title' => esc_html( $context['title'] ),
	11404	+ 'href' => $context['href'],
	11405	+ )
	11406	+ );
	11407	+ }
	11408	+
	11409	+ foreach ( $types as $slug => $type ) {
	11410	+ if ( empty( $type['visible'] ) || isset( $emitted[ $slug ] ) ) {
	11411	+ continue;
	11412	+ }
	11413	+ $wp_admin_bar->add_node(
	11414	+ array(
	11415	+ 'id' => 'xspeed-purge-' . $slug,
	11416	+ 'parent' => 'xspeed-purge',
	11417	+ 'title' => esc_html( $type['label'] ),
	11418	+ 'href' => self::purge_type_url( $slug ),
	11419	+ )
	11420	+ );
	11421	+ }
2011	11422	}
2012	11423
	11424	+ /**
	11425	+ * Nonce-protected admin-post URL for purging a single type. The nonce
	11426	+ * action is per-type so a leaked URL can't be replayed for a different
	11427	+ * scope.
	11428	+ */
	11429	+ private static function purge_type_url( string $type ): string {
	11430	+ return wp_nonce_url(
	11431	+ admin_url( 'admin-post.php?action=xspeed_purge&type=' . rawurlencode( $type ) ),
	11432	+ 'xspeed_purge_' . $type
	11433	+ );
	11434	+ }
	11435	+
2013	11436	public function handle_admin_bar_purge() {
2014	11437	if ( ! current_user_can( 'manage_options' ) ) {
2015	11438	wp_die( esc_html__( 'Unauthorized.', 'xspeed' ), 403 );
2016	11439	}
2017		- check_admin_referer( 'xspeed_purge' );
2018		- self::purge_all();
2019		- wp_safe_redirect( wp_get_referer() ?: admin_url() );
	11440	+ $type = isset( $_GET['type'] ) ? sanitize_key( wp_unslash( $_GET['type'] ) ) : 'all';
	11441	+ check_admin_referer( 'xspeed_purge_' . $type );
	11442	+
	11443	+ // Only honour known types; anything else falls back to a full purge.
	11444	+ if ( ! array_key_exists( $type, self::purge_types() ) ) {
	11445	+ $type = 'all';
	11446	+ }
	11447	+
	11448	+ // Answer the browser BEFORE purging. "Purge All" fans out to the local
	11449	+ // sweep, the object cache, CSS/edge listeners (outbound HTTP) and
	11450	+ // third-party render caches, all in this one request — on a large site
	11451	+ // that can outlive PHP-FPM's request_terminate_timeout, FPM kills the
	11452	+ // worker mid-purge, and nginx answers the admin's click with a 502.
	11453	+ // fastcgi_finish_request() exists on exactly those FPM setups: send
	11454	+ // the redirect, close the connection, then keep purging in the same
	11455	+ // process. Elsewhere (mod_php, CLI tests) fall back to purge-then-
	11456	+ // redirect as before.
	11457	+ $redirect = self::safe_purge_redirect( wp_get_referer() );
	11458	+ if ( function_exists( 'ignore_user_abort' ) ) {
	11459	+ ignore_user_abort( true );
	11460	+ }
	11461	+ if ( function_exists( 'set_time_limit' ) ) {
	11462	+ @set_time_limit( 300 ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- best-effort under safe-mode-like restrictions.
	11463	+ }
	11464	+ if ( function_exists( 'fastcgi_finish_request' ) ) {
	11465	+ wp_safe_redirect( $redirect );
	11466	+ fastcgi_finish_request();
	11467	+ self::purge_type( $type );
	11468	+ exit;
	11469	+ }
	11470	+
	11471	+ self::purge_type( $type );
	11472	+ wp_safe_redirect( $redirect );
2020	11473	exit;
	11474	+ }
	11475	+
	11476	+ /**
	11477	+ * Resolve a safe redirect target for an admin-bar purge.
	11478	+ *
	11479	+ * The purge sends the admin back where they came from — but the referer
	11480	+ * can be a ONE-SHOT action URL (e.g. update.php?action=upload-plugin from
	11481	+ * installing a plugin zip, or any *.php?action=… that consumed a POST /
	11482	+ * temp upload). Redirecting there re-runs the action with nothing to act
	11483	+ * on, so WordPress dies — the classic "Please select a file" from
	11484	+ * File_Upload_Upgrader. Strip the transient action args so we return to a
	11485	+ * safe, re-GET-able view of the same page; fall back to the dashboard when
	11486	+ * there is no usable referer.
	11487	+ *
	11488	+ * @param string|false $referer Raw wp_get_referer() value.
	11489	+ * @return string Safe URL to redirect to.
	11490	+ */
	11491	+ public static function safe_purge_redirect( $referer ): string {
	11492	+ $referer = is_string( $referer ) ? $referer : '';
	11493	+ if ( '' === $referer ) {
	11494	+ return admin_url();
	11495	+ }
	11496	+
	11497	+ // A referer that lands on an action-processing endpoint (update.php,
	11498	+ // update-core.php, plugin/theme install/upload flows) can't be safely
	11499	+ // re-requested — send them to the dashboard instead of replaying it.
	11500	+ $path = (string) wp_parse_url( $referer, PHP_URL_PATH );
	11501	+ if ( preg_match( '#/wp-admin/(update|update-core)\.php$#', $path ) ) {
	11502	+ return admin_url();
	11503	+ }
	11504	+
	11505	+ // Otherwise keep them on the same page but drop the query args that
	11506	+ // would re-trigger a form action or upload on load.
	11507	+ return remove_query_arg(
	11508	+ array( 'action', 'action2', 'package', 'overwrite', 'plugin', 'theme', 'file', '_wpnonce', '_ajax_nonce' ),
	11509	+ $referer
	11510	+ );
2021	11511	}
2022	11512	}