Split wp-cache.php into per-responsibility inc/ files (#1061)#1065
Merged
Conversation
…ion bootstrap Part of #1061 (split wp-cache.php). Before relocating the cache-file stats cluster, pin its current behaviour with integration-tier characterization tests covering wp_cache_format_fsize(), wpsc_generate_sizes_array(), wpsc_dirsize() (wpcache/supercache + expired/cached classification, preload keep-fresh, meta skipping), and wp_cache_regenerate_cache_file_stats() (stats shape + supercache_stats option write). The plan slated these for the CI smoke tier, but the whole cluster lives in wp-cache.php (which the smoke bootstrap does not load) and the helpers call WordPress functions, so they run in the local integration tier instead. To make any wp-cache.php cluster function reachable under the real WP runtime, the integration bootstrap now force-loads wp-cache.php (it self-loads phase2 + inc/ files and runs wpsc_init()). Scope-exclude WordPress.WP.AlternativeFunctions for tests/php so fixtures may use direct filesystem calls.
Part of #1061 (split wp-cache.php). Before relocating the htaccess cluster, pin the current output of wpsc_get_htaccess_info() with integration-tier characterization tests: the rewrite condition list (POST/query-string exclusions, trailing-slash URI conditions, the logged-in/comment/postpass cookie guard), the mobile user-agent toggle, the UTF-8 charset toggle, the plain-permalink behaviour, and the gzip / Vary+Cache-Control header / mod_expires / Options-Indexes blocks. Also pins wpsc_get_logged_in_cookie(). The file-writing entry points (update_mod_rewrite_rules and add/remove wrappers) read/write the real .htaccess and fetch the live URL, so they are left to e2e; their rule content is produced by the generator covered here.
Part of #1061 (split wp-cache.php). Before relocating the settings-forms cluster, pin the current parse/sanitise/persist contract with integration-tier characterization tests: wp_cache_sanitize_value() (tag stripping, entity escaping, whitespace/comma splitting, var_export output), and the end-to-end updaters wp_cache_update_rejected_strings(), wp_cache_update_rejected_pages(), wpsc_update_tracking_parameters() (parsed values land in the runtime globals and the config file), plus wpsc_update_debug_settings()'s no-nonce snapshot return. Tests seed a temp config file and cache_path so wp_cache_replace_line / wp_cache_setting write to a throwaway file.
Part of #1061 (split wp-cache.php). Before relocating the preload subsystem, pin the preload state contract with integration-tier characterization tests: wpsc_get_preload_status() (idle default; reads the JSON status file), wpsc_update_active_preload() (running flag + newest-first history capped at 5), wpsc_update_idle_preload() (clears running/history, records finish time), wpsc_is_preload_active() (stop-flag / mutex / taxonomy marker / counter matrix), wpsc_reset_preload_counter(), and wpsc_reset_preload_settings() (clears markers + zeroes counter), plus wpsc_get_preload_status_file_path(). Completes the Phase A characterization net; all four logic clusters slated for relocation now have a green safety net (smoke 34, integration 37).
Relocate ~120 global functions out of the 4,500-line wp-cache.php into focused
inc/ files. Pure relocation: identical function names, signatures, hook names,
and load order; behaviour is preserved (smoke 34, integration 37, e2e 28 all
green). wp-cache.php is now a ~200-line thin loader: plugin header, constants,
the require_once include list, wpsc_init() + its init wiring, the frontend
disable-on-wp_die / set-home hooks, and the activation/deactivation/uninstall
registrations.
New / updated inc/ files:
- inc/boost.php - Jetpack Boost migration + the relocated install banner
- inc/plugins-cookies.php- WPSC plugin-list & extra-cookie management, feed GC
- inc/cache-files.php - cache-file listing/stats/sizing/cleaning + per-post invalidation
- inc/htaccess.php - .htaccess / mod_rewrite rule management
- inc/settings-forms.php - settings-page form handlers and validators
- inc/preload.php - the full preload subsystem
- inc/lifecycle.php - activation/deactivation/uninstall, enable/disable,
advanced-cache + config/cache-dir management, GC defaults
- inc/admin-notices.php - admin notices, plugin-row UI, front-page site check
- inc/admin-ui.php - the settings screen, menus, enqueues, render helpers
Necessary, behaviour-preserving deviations from a byte-for-byte move (things
that are position-dependent and cannot literally relocate):
- register_activation_hook / register_deactivation_hook / register_uninstall_hook
stay in wp-cache.php so __FILE__ resolves to the main plugin file; their
handlers live in inc/lifecycle.php.
- __DIR__ / __FILE__ references in the relocated admin-ui, lifecycle, and boost
banner code now resolve to the plugin root via dirname( __DIR__ ) (the inc/
files sit one level below root), preserving asset URLs, WPCACHEHOME, and
partial-template paths. (Caught by the e2e suite.)
Lint: the relocated procedural includes carry pre-existing WPCS debt verbatim
(modernization is out of scope, tracked as a follow-up), so they are excluded
in .phpcs.xml.dist with a documented rationale; wp-cache.php and newly authored
inc/ files (e.g. inc/boost.php) remain fully linted. The integration bootstrap
loads wp-cache.php so the relocated functions are exercised under a real WP
runtime; test fixtures may use direct filesystem calls.
Add CONTEXT.md (entry points, the inc/ file map, relocated-code conventions, test tiers) and ADR-0001 recording the split decision, the position-dependent deviations, and the WPCS-modernization follow-up.
This was referenced Jun 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1061 (executes #1047 item 4).
What
Splits the ~4,500-line
wp-cache.phpinto nine focusedinc/files by pure relocation — same function names, signatures, hook names, and load order; no behaviour change.wp-cache.phpis now a ~210-line thin loader (header, constants, therequire_oncelist,wpsc_init()+ init wiring, the frontendwp_die/set_homehooks, and the activation/deactivation/uninstall registrations).Preceded by a characterization test net (Phase A) for the four logic clusters most likely to regress silently.
inc/ file map
boost.php(Boost migration + relocated install banner) ·plugins-cookies.php·cache-files.php(+ per-post invalidation) ·htaccess.php·settings-forms.php·preload.php·lifecycle.php·admin-notices.php(+ front-page site check) ·admin-ui.php. SeeCONTEXT.mdanddocs/adr/0001-*.Necessary behaviour-preserving deviations from a literal move
Some code is position-dependent and cannot literally relocate:
register_activation_hook/register_deactivation_hook/register_uninstall_hookstay inwp-cache.phpso__FILE__resolves to the main plugin file; their handlers live ininc/lifecycle.php.__DIR__/__FILE__in relocated admin-ui / lifecycle / boost-banner code now resolves to the plugin root viadirname( __DIR__ ), preserving asset URLs,WPCACHEHOME,advanced-cache.phpgeneration, and partial-template paths. The e2e suite caught these — the unit/integration tiers don't exercise them.Lint policy
The relocated procedural includes carry pre-existing WPCS debt verbatim (modernization is out of scope and tracked as a follow-up), so they're excluded in
.phpcs.xml.distwith a documented rationale.wp-cache.phpand newly authoredinc/files (e.g.inc/boost.php) remain fully linted. Because the changed-lines linter diffs the cumulative branch against trunk, only the original and the fully-moved tree are lint-clean — hence the single relocation commit rather than one per cluster.Testing
composer lint— passescomposer test-php(CI smoke, PHPUnit 9.6, no DB) — 34 passingmake test-integration(local WP + DB) — 37 passingcomposer test-e2e(Docker/Jest) — 28 passing