=== LumenCache ===
Contributors:      nasruleam, celsiusanderson
Tags:              cache, full-page-cache, performance, woocommerce, page-speed
Requires at least: 6.0
Tested up to:      7.1
Requires PHP:      8.1
Stable tag:        1.6.24
License:           GPL-2.0-or-later
License URI:       https://www.gnu.org/licenses/gpl-2.0.html

RAM-first full-page caching that serves pages before WordPress loads, with automatic WooCommerce and LMS integration.

== Description ==

LumenCache implements a RAM-first full-page cache with a WordPress
`advanced-cache.php` drop-in. On a cache HIT, the drop-in serves complete HTML
before the normal WordPress bootstrap and database queries. This early-response
path reduces application-layer work and keeps repeat page requests fast across
Nginx, Apache, and LiteSpeed.

The cache is designed to fail open when its storage layer is unavailable, so a
cache connection problem does not take the WordPress site offline.

== Research Foundation ==

Academic Reference:
"Dynamic Resource Mapping in Zero-Reload Server Architectures: Eliminating
Application-Layer Latency and Extension Dependency in High-Concurrency CMS
personalised requests continue through the full WordPress stack.

This architecture is intended to reduce repeated bootstrap work, database
queries, and extension overhead while preserving WordPress compatibility. It
also provides a practical bridge between academic performance research and
everyday publishing workloads, including content-heavy sites, WooCommerce
catalogues, and membership-driven pages.

Research author: **Dean Nasrul Eam — Light & Composition University**.

= Eight-Subsystem Architecture =

1. **RAM-First Full-Page Cache Engine** — PHP stores complete HTML at
   `shutdown` and resolves repeat requests from the in-memory cache layer.
2. **Nginx / Apache Proxy Bridge** — Static or dynamic server config bypasses
   PHP entirely for cache hits.
3. **Selective Bypass Cookie Router** — `sys_active_state` cookie routes
   logged-in users and cart-active visitors to live PHP.
4. **Application Driver Profile Engine** — Auto-detects WooCommerce,
   LearnDash, LifterLMS, MemberPress, BuddyBoss and registers tailored bypass
   rules and invalidation hooks.
5. **Surgical Cache Invalidation** — Post save / nav menu / widget / theme
   switch events trigger precise per-URL or full purges.
6. **REST API State Endpoint** — `/wp-json/lumencache/v1/user-state` serves
   personalised fragments for skeleton-hydration clients.
7. **Skeleton Hydration DOM Worker** — `skeleton-hydration.js` replaces cached
   placeholders with live content on load.
8. **WP-CLI Management Interface** — `flush`, `flush-url`, `status` commands.

= Configuration (optional) =

All settings are configurable from **LumenCache → Settings** in the WordPress
admin. Optionally override any setting via wp-config.php — constants always win:

    define( 'LUMENCACHE_REDIS_HOST',          '127.0.0.1' );
    define( 'LUMENCACHE_REDIS_PORT',          6379 );
    define( 'LUMENCACHE_REDIS_SOCKET',        '' );
    define( 'LUMENCACHE_REDIS_PASSWORD',      '' );
    define( 'LUMENCACHE_REDIS_DATABASE',      0 );
    define( 'LUMENCACHE_REDIS_TIMEOUT',       1.0 );
    define( 'LUMENCACHE_REDIS_PREFIX',        'cache:' );
    define( 'LUMENCACHE_CACHE_TTL',           86400 );
    define( 'LUMENCACHE_CACHE_SALT',          '' );
    define( 'LUMENCACHE_CACHE_QUERY_STRINGS', false );
    define( 'LUMENCACHE_PROXY_PASSWORD',      '' );

= WP-CLI =

    wp lumencache flush
    wp lumencache flush-url https://example.com/page/
    wp lumencache status

== Installation ==

== Privacy ==

LumenCache stores rendered page HTML and cache metadata in the in-memory cache
service configured by the site administrator. It does not send cache contents,
visitor data, or analytics data to a third-party LumenCache service. The
optional user-state endpoint returns only the requested dynamic values to the
requesting browser; sites should review those values and their own privacy
policy before enabling personalized hydration.

== Frequently Asked Questions ==

= Why are 0 pages cached? =

Two common causes:
1. **Nginx config not applied** — visit Server Setup and paste the config blocks.
2. **WooCommerce session cookie** — fixed in v1.1.0. Previous versions bypassed
   the cache for *all* visitors on WooCommerce sites due to the always-present
   `wp_woocommerce_session_*` cookie.

= Why can key salting affect server-level caching? =

When `LUMENCACHE_CACHE_SALT` is set, PHP stores keys as SHA-256 hashes. A
server-level configuration must use the same key strategy or it will produce
cache misses. Disable the salt for a plain-key configuration, or use the
compatible hashed-key server template.

= Does LumenCache work with LiteSpeed? =

Yes. LiteSpeed supports Apache-compatible `.htaccess` rewrites. LumenCache uses
the Apache proxy mode on LiteSpeed. For better performance, ask your host
which in-memory cache acceleration options are available.

= Can I still use wp-config.php constants? =

Yes — constants always take precedence over admin settings. If you define a
constant, the corresponding field in the Settings tab is shown locked (read-only).

== Changelog ==

= 1.6.24 (August 23, 2026) =
* COMPATIBILITY: Tested and verified full compatibility with WordPress 7.1.
* PERFORMANCE: Verified pre-bootstrap drop-in execution, cache purging hooks, and REST API user-state endpoints on WordPress 7.1.

= 1.6.23 (August 15, 2026) =
* SECURITY: Added explicit ABSPATH direct access guard to `server/lumen-cache-proxy.php`.
* IMPROVEMENT: Updated `Htaccess::deploy_proxy()` to automatically configure localized ABSPATH definitions upon file deployment.

= 1.6.22 (August 15, 2026) =
* COMPLIANCE: Full compliance with WordPress.org Guideline 5; streamlined UI with clean external Pro link.
* DROP-IN: `advanced-cache.php` is now completely self-contained with compiled configuration snapshot data.
* SANITIZATION: Strict input and header sanitization against CRLF injection across all pre-bootstrap request paths.

= 1.6.21 (August 14, 2026) =
* HOUSEKEEPING: Updated Plugin URI to point to the official Dev Lab page.

= 1.6.20 (August 11, 2026) =
* FIX: Adjusted Quick Setup step flex rules in `assets/css/admin.css` to prevent connector lines from overlapping labels.

= 1.6.19 (August 11, 2026) =
* FIX: Replaced WordPress functions in `lumen-cache-proxy.php` with native PHP casts since the proxy runs pre-bootstrap.
* FIX: Corrected root path calculation (`LUMENCACHE_PROXY_ABSPATH`) for WordPress `index.php` and `wp-config.php` inclusion.

= 1.6.18 (August 11, 2026) =
* FIX: Added return value check on `$redis->auth()` and `$redis->select()` in `connect_phpredis()`.

= 1.6.17 (August 11, 2026) =
* PERF: Guarded debug string concatenation behind an explicit `LUMENCACHE_DEBUG` check for zero production overhead.

= 1.6.16 (August 11, 2026) =
* FIX: Replaced non-existent WordPress helper calls in `advanced-cache.php` with native PHP casts and isset checks.
* FIX: Corrected `enable_wp_cache()` string replacement logic for reliable `WP_CACHE` insertion into `wp-config.php`.

= 1.6.15 (August 11, 2026) =
* FIX: `Lifecycle::uninstall()` now flushes all Redis keys before removing plugin files.
* FIX: Corrected connection source label in Settings for manually-entered host/port settings.

= 1.6.14 (August 11, 2026) =
* SECURITY: Added direct file access protection via `ABSPATH` check to all server drop-ins.
* SANITIZATION: Sanitized all `$_SERVER` inputs across pre-bootstrap request paths.

= 1.6.13 (August 11, 2026) =
* FIX: Prevented RSS/Atom feeds from caching to avoid incorrect `Content-Type: text/html` response headers.
* FIX: Hardened URL sanitization in manual cache purge handler using `esc_url_raw()`.

= 1.6.12 (August 10, 2026) =
* NEW: Built-in WooCommerce cart-fragments guard against crawler-triggered fragment storms.

= 1.6.11 (August 9, 2026) =
* COMPLIANCE: Standardized update delivery on the official WordPress.org channel.
* DOCS: Added direct SSH installation instructions for Plesk in the Hosting Guide.

= 1.6.10 (August 9, 2026) =
* NEW: Added RAM Cache Engine connectivity check to Quick Setup and introduced the Hosting Guide tab.

= 1.6.9 (August 9, 2026) =
* IMPROVED: Quick Setup tracker review drawer for active, fully-configured sites.

= 1.6.8 (August 9, 2026) =
* NEW: Added interactive 4-step Quick Setup progress tracker on the Overview tab.

= 1.6.7 (August 9, 2026) =
* FIX: Aligned admin card headers and status badges across dashboard screens.

= 1.6.6 (August 8, 2026) =
* SECURITY: Synchronized MemberPress session cookie matching across Nginx, Apache, and PHP drivers.

= 1.6.5 (August 8, 2026) =
* FIX: Updated navigation references and doc comments for modular settings architecture.

= 1.6.4 (August 8, 2026) =
* UX: Refined dashboard sidebar layout with dedicated feature navigation panels.

= 1.6.3 (August 8, 2026) =
* CRITICAL: Added foreign drop-in protection to prevent overwriting existing third-party cache drop-ins.
* FIX: Aligned Redis timeout defaults and safety bypasses for dynamic/personal routes across all readers.
* FIX: Added non-HTML response rejection to prevent caching API/JSON payloads as HTML.

= 1.6.2 =
* IMPROVED: Refined update channel integration for WordPress.org directory hosting.

= 1.6.1 =
* UX: Instant click-to-show tabs across dashboard navigation.
* FIX: Fixed Admin Bar quick link URL routing.

= 1.6.0 =
* ARCHITECTURE: Split into clean Standard core with modular action/filter extensibility.
* UX: Single-page admin navigation shell with collapsible sidebar.

= 1.5.1 =
* FIX: Corrected LiteSpeed / OpenLiteSpeed server detection order.
* FIX: Added safe commented placeholders for salted Nginx configurations.

= 1.5.0 =
* NEW: Added Cloudflare edge cache purge integration support.

= 1.4.0 =
* NEW: Added cache telemetry diagnostics, bypass-reason counters, and connection test tooling.

= 1.3.0 =
* NEW: Automatic detection and bypass integration for XML sitemaps.

= 1.2.9 =
* NEW: Automatic application driver integration for educational courses and custom post types.

= 1.2.8 =
* COMPATIBILITY: Verified compatibility with WordPress 7.0 and PHP 8.5.

= 1.2.7 =
* FIX: Intelligent handling of all three `WP_CACHE` states in `wp-config.php` and automated cleanup on deactivation.

= 1.2.6 =
* UX: Added context-aware validation for Nginx key salting configurations.

= 1.2.5 =
* UX: Context-aware badges in Security Hardening Matrix and direct key salt generator.

= 1.2.4 =
* FIX: Added tracking-parameter stripping to Apache proxy to maintain parity with PHP cache keys.

= 1.2.3 =
* CRITICAL: Fixed phpredis `SCAN` cursor handling in `key_count()` and `delete_pattern()`.

= 1.2.2 =
* FIX: Automated stripping of 14 marketing tracking query parameters (Google Shopping, Meta Ads, etc.).

= 1.2.1 =
* FIX: Added connection return validation in `connect_phpredis()` and refined Unix socket handling.

= 1.2.0 =
* FIX: Output buffering rebuild for PHP-FPM and Nginx FastCGI environments.

= 1.1.1 =
* NEW: Standalone `advanced-cache.php` drop-in deployment with zero server configuration requirements.

= 1.1.0 =
* NEW: Admin settings interface, Admin Bar menu, and WP Dashboard widget.
* FIX: Resolved WooCommerce session cookie over-bypass for dramatic cache hit rate improvements.

= 1.0.3 =
* Initial public release.

== Upgrade Notice ==

= 1.6.24 =
WordPress 7.1 compatibility release. Recommended update for all users.
