13 — Caching and performance#

The performance model is deliberately crude, because crude survives shared hosting: published pages are rendered to HTML files and served from disk. No Redis, no reverse proxy, no edge, no assumptions about the host beyond a writable storage/.

13.1 Cache layers#

HTML is sent with Cache-Control: no-cache so a visitor always revalidates and a published change is visible immediately, plus an ETag so the response is usually a 304. Serving HTML from our own file cache is fast; letting a browser hold a stale page for minutes is not worth the risk of an owner saying "I published it and nothing changed".

13.2 Page cache keys and files#

storage/app/kodepress-cache/
└── site-1/
    ├── bn/
    │   ├── _index.html                 # the homepage
    │   ├── about.html
    │   └── blog/
    │       ├── _index.html
    │       ├── _index--page-2.html
    │       └── my-first-post.html
    └── en/
        └── about.html

The key is site_id / locale / path [/ page-N] [/ year]:

Device is not in the key: responsive CSS handles layout, and device-based menu visibility is done with CSS classes precisely so the cache stays single-variant. Query strings are not in the key: a page with a query string that affects output (search, pagination beyond page) is not cached at all.

Each entry is two files: about.html and about.meta.json (rendered-at timestamp, content hash, locale, the page id, and the dependency list from the usage index). The metadata is what makes targeted invalidation and cache reporting possible.

13.3 Invalidation rules#

CacheInvalidator is the only place that maps a model event to a clear. Models fire events; the invalidator decides. Nothing else calls HtmlCache::forget*.

Why "all pages" is acceptable. Header, footer, menu and theme changes are rare (a handful per month on a live site) and clearing is cheap — it is a directory delete. The cost is re-rendering on the next visit, roughly 150–400 ms per page on the target host, once per page. The alternative (partial templating with fragment caching) adds a class of "stale header on one page" bugs that a non-technical owner cannot diagnose. See ADR-0007.

13.4 What is never cached#

• Any request from an authenticated user (so inline editing and the edit bar always work, and an editor never sees their own stale page).
• The search page.
• A page containing a block with cacheable: false (Login/Account, live Search).
• Any request with a query string other than page.
• POST and every other non-GET method.
• Preview routes.
• The admin area (obviously), which also sends no-store.

A page skipped for one of these reasons records the reason in a debug header (X-KodePress-Cache: bypass; reason=auth) when APP_DEBUG is on, so "why is this page slow?" has an answer.

13.5 Warming#

• kodepress:cache-warm renders the homepage and the N most recently published pages (default 20). It runs after a deploy, after a chrome-wide clear, and nightly.
• Warming is chunked: it renders at most 10 pages per cron tick and keeps a cursor, so it never trips a shared-hosting time limit.
• Warming is best-effort. A failed render logs and moves on; it never blocks a deploy.

13.6 Public page performance budget#

Measured on the target class of host (shared cPanel, no opcode preloading, spinning or modest SSD):

A test asserts the query count on a cache miss and the asset counts; budgets that are not tested are decoration.

13.7 Front-end delivery#

• One stylesheet (the compiled theme) and one script bundle. Block-specific CSS is appended to the theme file for blocks actually in use on the site, decided at compile time from the usage index.
• The script bundle is Alpine plus the small set of behaviours (sticky header, drawer, mega panel, accordion, lightbox, dismissible bar, back-to-top). It is deferred. Nothing in the public output requires JavaScript to read the content — menus render as links, accordions start open-first, images are real <img> tags.
• public/build is committed, so the server needs no Node; the Vite manifest hash in filenames handles busting.
• Fonts: 2 woff2 files preloaded, font-display: swap, self-hosted.
• No third-party requests unless the owner adds an analytics snippet or enables a captcha.

13.8 Admin performance#

13.9 Observability on a host with no tooling#

• Dashboard -> System shows: last cron tick, cache size and entry count, queued scheduled posts, disk free, PHP version, image driver, last backup, last deploy commit.
• storage/logs rotates daily with 14 days kept. The dashboard surfaces the count of errors in the last 24 hours with a link, because an owner will never read a log file.
• kodepress:doctor (11) is the one command to run when something feels wrong.
• A X-KodePress-Render: 142ms; cache=miss header is emitted when APP_DEBUG is on.

13.10 Tests for this document#

KodePress documentation · generated from the Markdown sources by tools/build-docs-site.py · internal preview, not indexed.