Simple Website Framework

Caching

Monday April 20th, 2026

Written by Scary le Poo

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):

  1. top-cache.php starts an output buffer with ob_start()
  2. The page renders normally through the full PHP stack
  3. bottom-cache.php writes 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):

  1. top-cache.php detects the file and serves it directly with readfile()
  2. 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=yes debug overlay always reflects live state, because ?meta requests skip the cache altogether
  • Paginated archive pages (?page=2 etc.) 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.