The framework includes a built-in server-side HTML cache. When enabled, fully rendered pages are saved as .html files on disk and served directly on subsequent requests, bypassing PHP rendering entirely until the cache expires.
Enabling the Cache
Caching is controlled by a single variable in config/config.php:
$enableHTMLCacheServe = true;
Set it to false during development (the default) so every request renders fresh. Enable it for production.
How It Works
The cache is implemented across two files: required/top-cache.php (included near the top of index.php) and required/bottom-cache.php (included near the bottom).
On a cache miss (no cached file exists, or the cached file has expired):
top-cache.phpstarts an output buffer withob_start()- The page renders normally through the full PHP stack
bottom-cache.phpwrites the buffered output to a cache file on disk, then flushes it to the browser
On a cache hit (a valid, unexpired cache file exists):
top-cache.phpdetects the file and serves it directly withreadfile()- Execution stops immediately — no Markdown parsing, no metadata extraction, no plugin loading
Cache File Naming
Cache files are named after the full URL path of the request, with / written as --, and stored in the site root. A request to /about produces cached-about.html; /services/roofing produces cached-services--roofing.html, so two pages with the same name in different folders never share a file; the home page requested as / is cached-root.html. A paginated archive adds the page number: /archives?page=2 is cached-archives--page-2.html.
Query parameters (other than ?page) are stripped before the cache filename is determined, so parameterised requests don't create duplicate cache entries. Three parameters bypass the cache entirely — the request is neither served from nor written to it: ?meta (the debug overlay), ?editor (the old editor shortcut) and ?preview (an editor preview draft, which must never be written to disk).
Cache Duration
The default cache lifetime is 5 hours (18,000 seconds). To change this, edit the $cachetime variable in required/top-cache.php:
$cachetime = 18000; // Seconds — 18000 = 5 hours
Adjust this to suit how frequently your content changes. A personal blog with occasional updates could safely use a much longer duration.
Busting the Cache
During development, the simplest approach is to leave caching disabled entirely ($enableHTMLCacheServe = false).
In production, if you need to force a page to regenerate immediately, delete the relevant cached-*.html file from the site root. The next request will render the page fresh and write a new cache file.
To clear all cached pages at once:
rm cached-*.html
What the Cache Does Not Cover
- The RSS feed (
?rss) bypasses the cache entirely — it is generated fresh on every request - The
?meta=yesdebug overlay always reflects live state, because?metarequests skip the cache altogether - Paginated archive pages (
?page=2etc.) are cached separately, one file per page number
Only ?page=N, where N is a whole number from 1 up, has any effect on what is cached. Every other query string is ignored: /about?utm_source=x is served from, and written to, the same cached-about.html as /about, and a request with a non-numeric or out-of-range page is rendered live and never stored. Nothing a visitor can put in a URL therefore ends up in the file everyone else receives — which is also why the canonical link and og:url the themes print are built from the path alone and escaped, not from the raw request.