Core Page Cache #1

New Issue

2026-09-13T07:22:08Z

kevin.bataille commented

2026-09-13 07:22:08 +00:00

Problem Statement

WordPress serves dynamic PHP pages on every request, which is slow for anonymous visitors. We need a full-page caching system that generates static HTML files and serves them directly.

Solution

Implement a page cache that captures the output of WordPress on first anonymous visit, stores it as a static HTML file, and serves that file directly on subsequent visits without loading WordPress.

User Stories

As a site owner, I want anonymous visitors to receive cached HTML pages, so that my site loads faster
As a site owner, I want the cache to auto-purge when I publish or update content, so that visitors always see fresh content
As a site owner, I want a manual purge button in the admin bar, so that I can quickly clear the cache when needed
As a site owner, I want to exclude logged-in users from cache, so that they always see dynamic content
As a site owner, I want to exclude specific pages (cart, checkout, account) from caching, so that e-commerce functionality works correctly
As a site owner, I want to exclude URLs by pattern, so that I have fine-grained control over caching
As a site owner, I want optional separate cache for mobile devices, so that responsive sites serve correct layouts
As a site owner, I want cache preloading via sitemap crawling, so that popular pages are always warm
As a site owner, I want to see cache statistics (hit rate, file count, size), so that I can monitor performance
As a site owner, I want the cache to work with multisite installations, so that each site in the network is cached independently
As a site owner, I want cache bypass for query strings, so that dynamic parameters are handled correctly
As a site owner, I want the cache to respect Don't Cache headers, so that third-party plugins can control caching

Implementation Decisions

Use WordPress advanced-cache.php drop-in for early cache serving
Output buffering via ob_start/ob_get_contents/ob_end_flush to capture HTML
Cache files stored in wp-content/cache/wp-recache/
Cache detection via WordPress rewrite rules or request analysis
File-based caching (no database dependency for cache storage)
Cache key based on URL, device type, and user state

Testing Decisions

Test that first anonymous visit generates cache file
Test that subsequent visits serve cached file
Test cache purge on post publish/update
Test exclusion rules (logged-in, specific pages, patterns)
Test mobile cache separation
Test cache preloading from sitemap
Test multisite compatibility

Out of Scope

Object caching (database query cache)
CDN integration (Phase 4)
Server-level caching (Varnish, Redis)

Further Notes

This is the foundation feature. All other features depend on this being solid.

## Problem Statement WordPress serves dynamic PHP pages on every request, which is slow for anonymous visitors. We need a full-page caching system that generates static HTML files and serves them directly. ## Solution Implement a page cache that captures the output of WordPress on first anonymous visit, stores it as a static HTML file, and serves that file directly on subsequent visits without loading WordPress. ## User Stories 1. As a site owner, I want anonymous visitors to receive cached HTML pages, so that my site loads faster 2. As a site owner, I want the cache to auto-purge when I publish or update content, so that visitors always see fresh content 3. As a site owner, I want a manual purge button in the admin bar, so that I can quickly clear the cache when needed 4. As a site owner, I want to exclude logged-in users from cache, so that they always see dynamic content 5. As a site owner, I want to exclude specific pages (cart, checkout, account) from caching, so that e-commerce functionality works correctly 6. As a site owner, I want to exclude URLs by pattern, so that I have fine-grained control over caching 7. As a site owner, I want optional separate cache for mobile devices, so that responsive sites serve correct layouts 8. As a site owner, I want cache preloading via sitemap crawling, so that popular pages are always warm 9. As a site owner, I want to see cache statistics (hit rate, file count, size), so that I can monitor performance 10. As a site owner, I want the cache to work with multisite installations, so that each site in the network is cached independently 11. As a site owner, I want cache bypass for query strings, so that dynamic parameters are handled correctly 12. As a site owner, I want the cache to respect Don't Cache headers, so that third-party plugins can control caching ## Implementation Decisions - Use WordPress advanced-cache.php drop-in for early cache serving - Output buffering via ob_start/ob_get_contents/ob_end_flush to capture HTML - Cache files stored in wp-content/cache/wp-recache/ - Cache detection via WordPress rewrite rules or request analysis - File-based caching (no database dependency for cache storage) - Cache key based on URL, device type, and user state ## Testing Decisions - Test that first anonymous visit generates cache file - Test that subsequent visits serve cached file - Test cache purge on post publish/update - Test exclusion rules (logged-in, specific pages, patterns) - Test mobile cache separation - Test cache preloading from sitemap - Test multisite compatibility ## Out of Scope - Object caching (database query cache) - CDN integration (Phase 4) - Server-level caching (Varnish, Redis) ## Further Notes This is the foundation feature. All other features depend on this being solid.

kevin.bataille added the phase-1 label 2026-09-13 07:28:48 +00:00

kevin.bataille referenced this issue from a commit

2026-09-13 11:45:04 +00:00

feat: implement Phase 1 - Core Page Cache and Admin Settings UI

kevin.bataille closed this issue

2026-09-13 11:45:04 +00:00

kevin.bataille referenced this issue

2026-09-13 11:50:22 +00:00

Rejected-cookie cache exclusions (WooCommerce cart) #10

Sign in to join this conversation.