Wonderful Relations uses several cache layers. They are derived runtime state: they make rendering and configuration lookup faster, but the database, shipped Data Bundles and generated runtime bundles remain the source of truth.
Cache layers
| Layer | What it stores | Typical invalidation |
|---|---|---|
| Query View | Compiled SQL and result payloads for query views. | Query cache clear, bundle sync, full cache flush. |
| WRDO Snapshot | Structural rows such as forms, datatables, queries and templates by UUID. | Bundle bootstrap or metadata save. |
| Render Plan | Compiled per-template render plans used by the Hot / Native renderer. | Bundle sync, render-plan rebuild, full cache flush. |
| Dynamic Options | Runtime options for dynamic form fields and DataTable filters. | Entity/query version bump, bundle import/sync, manual flush. |
| Runtime Catalog | Compiled bundle-backed configuration catalog. | Regenerate bundles from DB, catalog preflight, stale marker. |
Backend selection
The runtime cache backend is selected by wr_cache_backend or by the
WR_CACHE_BACKEND constant. Valid values are:
| Value | Behaviour |
|---|---|
auto | Use hybrid when an external object cache is available, otherwise file. |
file | Store cache entries as PHP files under the WR persistent cache directory. OPcache serves warm reads. |
object | Use WordPress wp_cache_*, usually backed by Redis or Memcached. Falls back to file if no external object cache is active. |
hybrid | Route small/hot groups through object cache and large render-plan payloads through file cache. |
null | Disable WR runtime caches. Use only for emergency debugging. |
WR_CACHE_BACKEND wins over the admin setting and is the safest
emergency override from wp-config.php.
Operator UI
Open Wonderful Relations → Cache Settings to inspect and manage the active cache state. The page shows:
- the resolved backend and whether an external object cache is detected;
- every cache group with its purpose, entry count and size when the backend can report it cheaply;
- Redis connection details when WordPress is using an object-cache drop-in;
- buttons for per-group flushes, full runtime flushes, runtime catalog preflight, benchmark and bundle regeneration.
The Flush all WR caches action calls the shared maintenance path. It flushes render plans, Query View cache, all WR cache groups, the compiled catalog and WordPress object cache, then arms the lazy compile marker so the next request can rebuild derived plans.
Dynamic options
Dynamic form-field and DataTable-filter options are cached separately from query results. Cache keys include field/query UUIDs, request parameters, locale, user or group scope and dependency versions.
The default policy stores bounded option lists only:
- public-scope options get a longer TTL;
- user/group-scoped options get a shorter TTL;
- very large option lists are not cached;
- entity and query edits bump dependency versions instead of scanning every cache key.
Disable Dynamic Options cache only while debugging live option queries. Disabling also flushes dynamic option payloads.
Runtime catalog
The runtime catalog lets WR serve structural configuration from on-disk bundle files instead of SQL. It is off by default. Enable it only after the preflight is green on the target install.
Two toggles exist:
- Runtime catalog for global structural configuration.
- DataTable runtime catalog for DataTable runtime records. Keep this off until DataTable parity is green, because DataTables are the most sensitive runtime surface.
If backend metadata changes while the catalog is enabled, WR marks the catalog stale and falls back to the database path until bundles are regenerated.
Diagnostics
For short measurements, enable the optional X-WR-Cache-Stats response
header through the admin setting or WR_CACHE_STATS_HEADER. It reports
the resolved backend plus per-request hit/miss counters per cache group.
Keep it off for normal public traffic.
Use the header with curl or benchmark tooling when you need to compare
cache behaviour before and after a change without parsing the admin UI.
Safe operating rules
- Do not delete files under
wp-content/wonderful-relations-data/manually. Some JSON files are persistent runtime state, not disposable cache. - Prefer Cache Settings → Flush all WR caches or
wp wr cache flushover clearing individual folders. - Regenerate project bundles from the live database before enabling the runtime catalog on a long-lived install.
- Treat cache misses as normal. Every cache layer is best-effort and should fall back to database or bundle sources when stale or corrupt.