Caching

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 based on the URL path of the request. The file is stored in the site root directory as cached-[pagename].html. For example, a request to /about produces cached-about.html.

Query parameters (other than ?meta and ?page) are stripped before the cache filename is determined, so parameterised requests don't create duplicate cache entries.

---

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 is preserved across cached requests because ?meta is in the list of query parameters that are kept when determining the cache filename
• Paginated archive pages (?page=2 etc.) are also preserved for the same reason