Story 3 — Cache-clearing scope enforcement #8701

Context

Part of the CDN refactor epic (#8693). Rewires cache-clear triggers so they only fire on toggle flip or an active mode's own setting change — not on tab navigation (spec §1.3).

Depends on Story 1 (state) and Story 2 (toggle events to hook into).

Task 3.1 — Rewire cache-clear triggers (3 pts)

Where to change:

• inc/Engine/CDN/Subscriber.php (WP_Rocket\Engine\CDN\Subscriber) — the maybe_clear_cache() method is hooked to update_option_wp_rocket_settings and currently diffs the old vs new cdn option; expand the diff to compare the three new toggle fields from Story 1 (rocketcdn_free_enabled, rocketcdn_pro_enabled, cdn_byocdn_enabled) and skip clearing when only a non-toggle field changed (e.g. tab focus state)
• The existing maybe_clear_cname_cache() in the same class clears CNAME validation transients (rocket_cname_valid_*) when cdn_cnames changes; this logic stays but must not fire on a tab-switch event that doesn't touch cnames

Key diff pattern to follow (already in maybe_clear_cache()):

$old_cdn = (bool) $old_value['cdn'];
$new_cdn = (bool) $value['cdn'];
if ( $old_cdn !== $new_cdn ) { ... }

Replicate for each new toggle field; exit early if none of the toggle fields changed.

Acceptance criteria:

• Given a user switches tabs without toggling, When they navigate, Then no cache clear fires.

Task 3.2 — Per-mode clearing scope (2 pts)

Where to change:

• inc/Engine/CDN/Cache.php (WP_Rocket\Engine\CDN\Cache) — already has clear_all_cache() and clear_rocketcdn_free_pages_cache(); the latter queries the wpr_rocket_cdn database table via WP_Rocket\Engine\CDN\RocketCDN\Database\Queries\RocketCDN::get_all() and purges only those URLs
• inc/Engine/CDN/Subscriber.php — maybe_clear_cache() already branches on Context::get_driver() (which returns one of ROCKETCDN_FREE_TYPE, ROCKETCDN_PAID_TYPE, BYOCDN_TYPE); update to use the new Applied-CDN-state resolver from Story 1 for the branch condition
• Upgrade → Pro while Free active: when the new state is PRO but the old state was FREE, always call clear_all_cache() regardless of Free's page list

Acceptance criteria:

• Given RocketCDN Free is toggled on or off on its own, When the toggle changes, Then only Free's listed pages are cleared (via Cache::clear_rocketcdn_free_pages_cache()).
• Given the user upgrades to Pro while Free is active, When Pro activates, Then the clear is site-wide (Cache::clear_all_cache()), not page-scoped.

Task 3.3 — Tests for §1.3 scenario table (2 pts)

Where: tests/Unit/inc/Engine/CDN/Subscriber/ — follow pattern of Subscriber/maybeClearCnameCache.php and Subscriber/upgradeCDN.php.

What to cover:

• Tab-switch with no toggle change → no clear
• Free toggle off → clear_rocketcdn_free_pages_cache() called, not clear_all_cache()
• Pro toggle on while Free active → clear_all_cache() called
• Other CDN toggle on/off → clear_all_cache()
• Add/remove individual Free page → page-only clear (existing behaviour, regression guard)

Decision needed

Issue #8464 conflicts with §1.3: it expects no clear on Pro subscription creation, but the spec requires site-wide clear. Needs a product call before Task 3.2 acceptance criteria are final.

Dependencies

• Blocked by Stories 1 & 2
• Blocks Stories 6, 7, 8, 9

Sizing

7 pts total