allignol/cache-buster

Cache buster for CSS, JS, fonts, SVG, PDF and images with advanced configuration options

1.0.0 2026-02-06 17:54 UTC

Requires

• getkirby/cms: ^3.8 || ^4.0 || ^5.0
• getkirby/composer-installer: ^1.1

MIT

• Sylvain Allignol

README

A simple and lightweight Kirby plugin to handle cache busting for CSS, JS, fonts, SVG, PDF and images with advanced configuration options.

Features

• Automatic cache busting for CSS, JS, fonts, SVG, PDF and images
• Multiple hash methods (MD5, SHA1, SHA256, XXH3, Timestamp)
• Customizable hash prefix and suffix
• Helpers and field methods

Installation

Via Composer (recommended)

composer require allignol/cache-buster

Add the following rules to the .htaccess file at the root of your site:

# --------------------------------------------------------
# Cache busting for CSS, JS, fonts, SVG, PDF and images
# --------------------------------------------------------

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.+)\.([a-zA-Z0-9]+)\.(css|js|woff2?|ttf|svg|pdf|jpe?g|png|gif|webp|avif)$ $1.$3 [L,NC]

Configuration

Add options to your config.php:

return [
    'allignol.cache-buster' => [
        'active' => true,              // Enable/disable the plugin
        'method' => 'xxh3',            // Hash method: md5, sha1, sha256, xxh3, timestamp
        'prefix' => '',                // Prefix before the hash (a-z, A-Z, 0-9, -, _)
        'suffix' => '',                // Suffix after the hash (a-z, A-Z, 0-9, -, _)
    ]
];

Available Hash Methods

All hash methods use the file's modification timestamp as their source. The hash obscures the actual modification date for security reasons while still ensuring the URL changes when the file is updated.

• xxh3 (default): Fast and efficient hash algorithm - produces a 16-character hash from the timestamp
• md5: MD5 hash - produces a 32-character hash from the timestamp
• sha1: SHA1 hash - produces a 40-character hash from the timestamp
• sha256: SHA256 hash - produces a 64-character hash from the timestamp
• timestamp: Direct file modification timestamp - uses the raw timestamp (not recommended for production as it exposes modification dates)

Note: If the file doesn't exist or its modification time cannot be determined, the plugin returns the original URL unchanged (no cache busting applied).

Supported File Types

The plugin automatically processes these file types:

• css - Stylesheets
• js - JavaScript files
• woff, woff2 - Web fonts
• ttf - TrueType fonts
• svg - SVG files
• pdf - PDF documents
• jpg, jpeg - JPEG images
• png - PNG images
• gif - GIF images
• webp - WebP images
• avif - AVIF images

Usage

Automatic (Components)

The plugin automatically handles css() and js() helpers:

<?= css('assets/css/style.css') ?>
// Output: <link href="assets/css/style.a1b2c3d4.css" rel="stylesheet">

<?= js('assets/js/script.js') ?>
// Output: <script src="assets/js/script.e5f6g7h8.js"></script>

Helpers

Use the provided helper functions in your templates:

// Cache buster (auto-detects extension)
<?= cacheBust('assets/css/style.css') ?>
// Output: assets/css/style.a1b2c3d4.css

<?= cacheBust('assets/js/script.js') ?>
// Output: assets/js/script.e5f6g7h8.js

// Works with absolute URLs too (e.g., from asset()->url())
<?= cacheBust(asset('images/logo.svg')->url()) ?>
// Output: https://yoursite.com/assets/images/logo.a1b2c3d4.svg

// Get only the hash
<?= cacheBustHash('assets/css/style.css') ?>
// Output: a1b2c3d4

Field Methods

Use cache buster on field values when you store file paths in custom fields.

Useful when:

• Users can configure custom stylesheets or scripts via the panel
• You have flexible templates with dynamic asset loading
• Custom icons, fonts, or documents are stored in text fields

Example blueprint:

fields:
  customStylesheet:
    type: text
    label: Custom Stylesheet
    placeholder: assets/css/custom.css
  brochurePdf:
    type: text
    label: Product Brochure
    placeholder: documents/brochure.pdf

Usage in templates:

// Custom stylesheet
<?php if ($url = $page->customStylesheet()->cacheBust()): ?>
    <link href="<?= $url ?>" rel="stylesheet">
<?php endif ?>

// PDF download link
<?php if ($url = $page->brochurePdf()->cacheBust()): ?>
    <a href="<?= $url ?>">Download brochure</a>
<?php endif ?>

Using the Class Directly

For advanced usage, you can use the CacheBuster class directly:

use Allignol\CacheBuster\CacheBuster;

$cacheBuster = new CacheBuster();

// Get busted URL
$url = $cacheBuster->bust('assets/css/style.css');

// Check if active
if ($cacheBuster->isActive()) {
    // ...
}

// Get current method
$method = $cacheBuster->method();

// Get all options
$options = $cacheBuster->options();

Example

// config.php
return [
    'allignol.cache-buster' => [
        'method' => 'md5',
        'prefix' => 'v-',
        'suffix' => '-cached'
    ]
];

Output: style.v-d41d8cd98f00b204e9800998ecf8427e-cached.css

License

MIT

Credits

• Sylvain Allignol