Problem
Pages are sent with Cache-Control: no-store, but the static files they load are cached according to the web server's defaults. With only a Last-Modified header, browsers decide on their own how long to keep a file. After an update, users can keep running the old files until that cache expires.
Example: after #9 (autosaved drafts) was deployed, the feature seemed broken until the browser was hard-refreshed, because the old wiki.js was still cached. Firefox for Android has no hard refresh at all; the only way there is to clear the cache.
Proposal
Add a small helper, for example assetURL($path) in functions.php. It returns the URL with a version parameter, ?v= plus the file's filemtime() (or a short hash of its content). Use it for every static resource the wiki references, so a changed file gets a new URL and is fetched again.
Resources to cover
wiki.js: loaded in printHeader().
- The stylesheet (
CSS_FILE, index.css by default): loaded in printHeader(). The file name is configurable.
- Icons under
icons/: toolbar, page actions, drawer, and w2-icon.png (favicon / apple-touch-icon).
url('/icons/internet.png') in index.css: PHP can't add a parameter inside the CSS. Instead, reference the image relative to the CSS file, so it is covered once the CSS URL is versioned, and rename the image if it ever changes.
- Uploads (
images/…): uploaded files can be overwritten under the same name (the upload form has an overwrite option), so images and links pointing to uploads stay stale. Add ?v=<filemtime> when rendering links and images that point to uploads, both in the Markdown rendering and in the uploads list.
Long-lived caching
Once all these URLs are versioned, send long cache headers for .js, .css, icons and uploads (e.g. Cache-Control: max-age=31536000, immutable). Browsers then stop rechecking unchanged files, and a changed file is still picked up right away because its URL changes.
- Apache:
.htaccess rules (mod_headers / mod_expires).
- nginx: matching rules in the example in INSTALL.md.
- Keep both in sync with the server-config tests in
tests/Server.
Not in scope
The icon paths are hard-coded as /icons/... without BASE_URI, which is tracked in #13. The new helper should build on that fix, or be done together with it, rather than fix it here.
Tests
- A unit test for the helper.
- An integration test checking that the page HTML references
wiki.js, the CSS, the icons and uploaded images with a ?v= parameter.
- Server tests (
tests/Server) checking that the cache headers are sent.
Problem
Pages are sent with
Cache-Control: no-store, but the static files they load are cached according to the web server's defaults. With only aLast-Modifiedheader, browsers decide on their own how long to keep a file. After an update, users can keep running the old files until that cache expires.Example: after #9 (autosaved drafts) was deployed, the feature seemed broken until the browser was hard-refreshed, because the old
wiki.jswas still cached. Firefox for Android has no hard refresh at all; the only way there is to clear the cache.Proposal
Add a small helper, for example
assetURL($path)infunctions.php. It returns the URL with a version parameter,?v=plus the file'sfilemtime()(or a short hash of its content). Use it for every static resource the wiki references, so a changed file gets a new URL and is fetched again.Resources to cover
wiki.js: loaded inprintHeader().CSS_FILE,index.cssby default): loaded inprintHeader(). The file name is configurable.icons/: toolbar, page actions, drawer, andw2-icon.png(favicon / apple-touch-icon).url('/icons/internet.png')inindex.css: PHP can't add a parameter inside the CSS. Instead, reference the image relative to the CSS file, so it is covered once the CSS URL is versioned, and rename the image if it ever changes.images/…): uploaded files can be overwritten under the same name (the upload form has an overwrite option), so images and links pointing to uploads stay stale. Add?v=<filemtime>when rendering links and images that point to uploads, both in the Markdown rendering and in the uploads list.Long-lived caching
Once all these URLs are versioned, send long cache headers for
.js,.css, icons and uploads (e.g.Cache-Control: max-age=31536000, immutable). Browsers then stop rechecking unchanged files, and a changed file is still picked up right away because its URL changes..htaccessrules (mod_headers/mod_expires).tests/Server.Not in scope
The icon paths are hard-coded as
/icons/...withoutBASE_URI, which is tracked in #13. The new helper should build on that fix, or be done together with it, rather than fix it here.Tests
wiki.js, the CSS, the icons and uploaded images with a?v=parameter.tests/Server) checking that the cache headers are sent.