Documentation

Docs

Installation, store selection, validation, and diagnostics for QuantumCache Free and Pro. This page reflects the configuration and operating surface present in the inspected plugin packages.

Version Requirements

Package Version inspected WordPress PHP Notes
QuantumCache Free 0.1.7 6.0+, tested to 6.9 8.0+ Redis optional; MySQL fallback available.
QuantumCache Pro 1.0.0 6.3+ 8.1+ Requires the quantumcache plugin to be active.

Redis is optional. If you want Redis mode, or want Auto mode to prefer Redis, the WordPress server needs a reachable Redis instance and the PHP Redis extension. If Redis is unavailable, QuantumCache can use its own MySQL-backed store.

Installation Basics

Free

  1. Upload the quantumcache plugin folder to /wp-content/plugins/ and activate it.
  2. Open Settings → QuantumCache.
  3. Choose a store mode: Auto, Redis, or MySQL.
  4. If you choose Redis, confirm the host, port, and database index.
  5. Load a public page twice and verify a cache hit using debug headers or WP-CLI.

On activation, QuantumCache creates its MySQL fallback tables for the current site. In multisite installs, network activation and new-site hooks create per-site tables as needed.

Pro

  1. Install and activate QuantumCache Free first.
  2. Install and activate quantumcache-pro.
  3. Open Settings → QuantumCache Pro.
  4. Enable only the Pro modules you intend to use, such as WooCommerce acceleration, logged-in caching, CDN integration, or metrics.

If you are running Pro directly from a source checkout rather than a packaged release, the inspected bootstrap expects its Composer autoloader to be present.

Store Modes

Auto

Auto mode is the safest default. QuantumCache applies saved Redis connection settings, probes Redis, and uses Redis when it is available. If the probe fails, it falls back to the MySQL store.

Advanced deployments can also force store selection with QUANTUMCACHE_FORCE_REDIS=1 or QUANTUMCACHE_FORCE_MYSQL=1.

Redis

Redis mode uses the PHP Redis extension and connects with QUANTUMCACHE_REDIS_HOST, QUANTUMCACHE_REDIS_PORT, and QUANTUMCACHE_REDIS_DB, or the equivalent saved settings.

  • Default host: 127.0.0.1
  • Default port: 6379
  • Default database: 0

Use Redis mode when you want QuantumCache pinned to Redis explicitly. Unlike Auto mode, explicit Redis mode does not provide a request-level MySQL fallback if Redis is unavailable.

MySQL

MySQL mode stores cache data in QuantumCache-owned tables: qc_entries and qc_tagmap. This is the portable fallback when Redis is not available.

Key Prefixing

QuantumCache prefixes keys per site. Advanced installations can override the base prefix with QUANTUMCACHE_KEY_PREFIX. If WP_CACHE_KEY_SALT is defined, QuantumCache incorporates a short salt into the generated prefix to reduce collisions in shared Redis environments.

Configuration Surface

Free

Settings → QuantumCache exposes:

  • Store mode: Auto, Redis, MySQL
  • Redis host, port, and database index
  • Auto fragment caching
  • Debug headers and HTML debug markers
  • Query TTL: default 86400 seconds
  • Query stale TTL: default 604800 seconds
  • Archive cache threshold: default 12 posts
  • Fragment TTL: default 600 seconds
  • Fragment stale TTL: default 86400 seconds
  • Purge Everything, Purge by Tag, and Purge by URL

The inspected Free package also supports the constants QUANTUMCACHE_REDIS_HOST, QUANTUMCACHE_REDIS_PORT, QUANTUMCACHE_REDIS_DB, QUANTUMCACHE_KEY_PREFIX, and QUANTUMCACHE_CACHE_LOGGED_IN. In Free, logged-in caching is off by default.

Pro

Settings → QuantumCache Pro exposes:

  • WooCommerce acceleration toggle
  • Logged-in page caching toggle
  • Allowed logged-in roles as CSV
  • Logged-in TTL
  • CDN integration toggle and provider selection for Cloudflare, Fastly, or LiteSpeed
  • Provider credentials and optional purge endpoint overrides
  • Metrics toggle, endpoint URL, bearer token management, and counter reset

The default logged-in role list in the inspected Pro config is subscriber,customer. The default logged-in TTL is 120 seconds.

Logged-In Caching

Free

Free is anonymous-first. Logged-in caching is disabled by default.

Pro

Pro adds role-scoped logged-in caching when it is explicitly enabled.

  • Default state: off
  • Default eligible roles: subscriber and customer
  • Default TTL: 120 seconds
  • Excluded paths include cart, checkout, my-account, admin, AJAX, and REST contexts
  • Logged-in fragment caching follows the same TTL override when enabled

WooCommerce Behavior

Free

Free can cache WooCommerce pages as general WordPress content, but it does not add the Pro-only WooCommerce rules below.

Pro

When WooCommerce acceleration is enabled and WooCommerce is present, the inspected Pro package adds:

  • Archive capture for shop and product taxonomy archives
  • A forced guest archive TTL of 90 seconds
  • Bypass rules for /cart/, /checkout/, /my-account/, and wc-ajax requests
  • Bypass for anonymous requests carrying WooCommerce cart or session cookies
  • Product invalidation hooks for product CRUD, stock changes, order impacts, term changes, reviews, and selected WooCommerce option updates
  • WooCommerce-specific key variance for sorting, pagination, price filters, layered navigation filters, locale, currency cookie, and geolocation parameter

WP-CLI

Free

  • wp quantumcache status
  • wp quantumcache flush

wp quantumcache flush --yes skips the confirmation prompt. wp quantumcache status reports the active backend, site prefix, storage stats, and lifetime event counters.

Pro

  • wp quantumcache pro:ping
  • wp quantumcache pro:metrics

wp quantumcache pro:metrics --reset --yes resets the persistent event counters.

Validation And Diagnostics

Basic Verification

  1. Enable Send X-QC debug headers in Settings → QuantumCache.
  2. Load a public page once and expect X-QC-Main: MISS.
  3. Load the same page again and expect X-QC-Main: HIT.
  4. Confirm the backend with X-QC-Store and X-QC-Store-Actual, or run wp quantumcache status.

Per-Request Bypass

Append ?qc_nocache=1 to bypass caching for that request. This is implemented in both the main-query and fragment-cache paths and is useful for debugging.

Free Diagnostics

  • Debug headers such as X-QC-Main, X-QC-Store, X-QC-Hydrated, X-QC-DB-Queries, X-QC-DB-Time, and X-QC-Store-Actual
  • Optional HTML fragment markers
  • Admin overview with active backend and key prefix
  • Live storage stats plus sampled key and tag diagnostics
  • Admin purge controls

Pro Diagnostics

  • Prometheus-format metrics endpoint with bearer-token protection
  • Metrics counter display in the Pro admin screen
  • Bearer token regeneration and counter reset actions
  • wp quantumcache pro:metrics for command-line inspection

On a guest request to /shop/, the inspected Pro package can emit X-QC-Pro-Force-TTL: 90 when the WooCommerce archive path is active. Cart, checkout, my-account, and wc-ajax requests should bypass the cache path.