Skip to content

Add version parameter to static resource URLs so browsers fetch updated files #21

Description

@codeling

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions