Cache — Reference
The Cache surface is the platform's invalidation and warm-up plane. It owns every layer of stored response that SGEN keeps in front of the database and the renderer — full-page HTML cache, object cache for query results, asset cache for compiled CSS / JS / fonts, and edge cache for image variants. Any time content changes and a stale copy keeps serving, the answer traces back to a layer managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping an invalidation workflow. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Cache lives under the Tools module in SG-Admin. The module renders two primary views — the cache status dashboard and the purge / warm-up control panel — and exposes a small set of write operations for purge (scoped or full), warm-up (scoped or full), regenerate compiled assets, and rebuild image variants.
The module is paired by convention: the dashboard half reads aggregated cache stats and renders the status; the control half handles invalidation writes and returns AJAX responses with the count of entries purged. Engineers reading the source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
A second surface — automatic invalidation — lives implicitly across every content module. When a page, post, menu, or setting changes, the writing module fires the corresponding cache purge without operator intervention. The manual surface described on this page exists for cases where the automatic layer missed an edge or where an operator wants to pre-warm before a traffic spike.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Tools → Cache
- URL prefix:
/sg-admin/cache/ - View templates:
application/views/Admin/Cache/
┌──────────────────────────────────────────────────────────────────────────┐│ SG-Admin → Tools → Cache [Purge ▾] [Warm ▾] │├──────────────────────────────────────────────────────────────────────────┤│ Layer Entries Hit rate Last purge ││ ────────────── ──────────── ──────────── ───────────────── ││ Page cache 1,284 pages 96.4 % 2 hr ago (scope=post) ││ Object cache 38,910 keys 91.7 % 14 min ago (auto) ││ Asset cache 67 bundles 100 % yesterday ││ Image variants 12,440 files 88.2 % 3 days ago ││ ││ [⋯ Purge layer] [⋯ Warm critical paths] [⋯ Regenerate assets] │└──────────────────────────────────────────────────────────────────────────┘Actions
The Cache surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
Read status
Returns aggregated stats per layer: entry count, hit rate over the trailing 24 hours, total size in bytes, last-purge timestamp, and last-purge scope (full / by-layer / by-path / by-tag). The status read is the only operation that hits the cache layer without mutating it.
Purge full
Drops every entry across every layer. The most aggressive operation the surface exposes. After full purge, every subsequent request rebuilds — first-byte time climbs sharply until the working set warms back up. Reserved for incidents where the cache state is known-corrupt or after a platform upgrade that changed the shape of cached values.
Purge by layer
Drops every entry within a single layer (page / object / asset / image). The other layers remain warm. Used when a class of stale content needs invalidating but a full purge would oversweep — for example, after a global menu change, drop the page cache and leave object cache intact.
Purge by path
Drops the page-cache entries that match a path or path prefix. Accepts a single path, a path glob (/blog/*), or a list. Bypasses every other layer. Used for surgical invalidation when one route is known stale and a wider purge would over-invalidate.
Purge by tag
Drops entries tagged with a given key. Every cached entry carries a tag set written by the producing module — a page-cache entry for /about carries page:42, menu:primary, setting:site_name. Purging by tag drops every entry whose set contains the tag. Used by the automatic invalidation layer when the underlying record changes.
Warm full
Iterates the canonical traffic set (the top-N most-requested paths from the trailing window) and issues internal requests to rebuild each. Bounded by a configurable concurrency ceiling so a warm-up cannot starve live traffic. Used after a planned full purge or before a known traffic spike.
Warm critical paths
A scoped warm — pre-renders the homepage, the top navigation targets, and any operator-pinned paths from the warm-up registry. Faster than full warm and intended as the standard post-purge step.
Regenerate compiled assets
Rebuilds compiled CSS, compiled JS, and font bundles. The asset cache stores compiled output keyed by source-file fingerprint; regenerate forces a rebuild even when the fingerprint is unchanged. Used after a theme edit when the operator wants to invalidate intermediate caches that are not directly visible.
Rebuild image variants
Re-derives the responsive variants (WebP / AVIF / size tiers) for every image in the Media library. The slowest operation on the surface — runs as an async job, posts progress back to the dashboard, emits a completion event to the Activity Log. Used after changing the image-variant configuration under Settings → Performance.
Engineering note — every purge action returns the count of entries dropped, not a boolean. Integrations that need to confirm an invalidation hit something should check that the count is non-zero, not that the call succeeded.
Data model
A cache entry carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
layer | enum | page, object, asset, image. |
key | string | Layer-specific identifier — path for page, query hash for object, fingerprint for asset, filename + size for image. |
value | blob | The cached payload. Never returned by the management surface. |
tags | array | Set of invalidation tags written by the producing module. |
size_bytes | integer | Storage footprint of the value. |
created_at | timestamp | When the entry was written. |
expires_at | timestamp | When the entry auto-expires. Null = no automatic expiry. |
hit_count | integer | Number of reads since creation. |
last_hit_at | timestamp | Most recent read. Drives the LRU eviction order. |
/about carrying tags page:42, menu:primary, setting:site_name is dropped when any of those three tags is purged. Producers write tags at cache-write time; consumers (modules emitting purges) reference tags at change time.LRU eviction. Each layer has a configured size ceiling under Settings → Performance. When the ceiling is reached, the layer evicts entries by least-recent-hit until under the ceiling. Eviction is silent — entries disappear without an event.
Stale-while-revalidate. When an entry's expires_at passes but no new write has invalidated it, the next read serves the stale value and triggers a background rebuild. Configurable per layer under Settings → Performance.
CACHE ENTRY (one per layer per key)├── layer enum page | object | asset | image├── key string path / hash / fingerprint / filename├── value blob never returned by mgmt surface├── tags array invalidation tag set├── size_bytes integer storage footprint├── created_at timestamp write time├── expires_at timestamp auto-expiry (null = manual only)├── hit_count integer reads since creation└── last_hit_at timestamp most-recent read (drives LRU)↓ on purge by tagEVERY ENTRY WHOSE tags INCLUDES tagis dropped across all layers↓ on layer ceiling reachedLEAST-RECENT-HIT entries evicted silently↓ on expires_at passednext read serves stale + triggers async rebuild(stale-while-revalidate, configurable per layer)Permissions
Access to the Cache surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Cache surface.
Layer 2 — per-action capability. Within SG-Admin, each Cache action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| Read status | ✔ | ✔ | ✔ |
| Purge full | ✔ | — | — |
| Purge by layer | ✔ | — | — |
| Purge by path | ✔ | ✔ | — |
| Purge by tag | ✔ | ✔ | — |
| Warm full | ✔ | — | — |
| Warm critical paths | ✔ | ✔ | — |
| Regenerate compiled assets | ✔ | — | — |
| Rebuild image variants | ✔ | — | — |
Rate-limiting. Purge full, regenerate assets, and rebuild image variants are rate-limited at the surface level. Repeated invocations within a configurable window (default 60 seconds) return a structured rejection naming the retry-after timestamp. The limit exists to prevent accidental purge-loops during incident response.
Audit. Every write — purge (any scope), warm (any scope), regenerate, rebuild — emits an Activity Log entry. The log records the acting operator, the action slug, the scope argument, and the count of entries affected. The rate-limit rejections are also logged so that pattern can be reviewed after the fact.
PURGE REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Rate-limit check │ too soon → reject with│ (purge full / rebuild) │ retry-after timestamp└─────────────┬─────────────┘│ passes▼purge executes│▼return count of entries dropped│▼Activity Log entry(scope + count, not the keys themselves)Related references
- Settings — Reference. Owns the layer size ceilings, the stale-while-revalidate window, the rate-limit defaults, and the image-variant configuration. Changes there reshape the Cache surface behavior.
- Cron Jobs — Reference. A periodic warm-up sweep and a periodic eviction sweep run on the cron surface. Modifying their schedule changes how aggressively cache is rebuilt or evicted.
- Activity Log — Reference. Source of the purge / warm / regenerate audit trail. Every write on this surface emits an entry there.
- Pages — Reference. Page edits emit automatic page-cache purges via the tag set. A page record carrying
tags = [page:42]invalidates on save. - Posts — Reference. Post edits emit automatic page-cache + object-cache purges. The category and tag pages tied to the post are dropped alongside the post itself.
- Media — Reference. Image uploads and edits emit automatic image-variant rebuilds. Replacing a source image cascades into the variant cache.
- Themes — Reference. Theme edits trigger asset cache regeneration. The compiled-asset fingerprint changes; the prior bundles drop on the next purge.
/docs/cache.