README

Fingerprints static assets for cache busting in Kirby projects.

General

The plugin provides a namespaced assets() helper function that adds a fingerprint to the filename for a given asset path.

For example, an asset path like /assets/styles/example.css becomes /assets/styles/example.8e5a39d7.css.

Usage

Installation

composer require kenshodigital/kirby-assets ^1.0

Setup

Kirby

Fingerprinting is disabled by default and needs to be activated explicitly in your config.php.

<?php declare(strict_types=1);

return [
    'kensho.assets' => [
        'fingerprint' => true,
    ],
];

The plugin uses Kirby’s configured assets root and URL. By default, this is the assets directory relative to the document root.

Further reading

• $kirby->root('assets')
• $kirby->url('assets')

Server

For performance reasons, the plugin doesn’t resolve fingerprinted assets via PHP automatically and relies on a server rewrite instead. Make sure to add the following rewrite to your server configuration.

Caddy/FrankenPHP

uri path_regexp ^(/assets/.+)\.(?:[a-f0-9]{8})\.([^.]+)$ $1.$2

Nginx

rewrite "^(/assets/.+)\.(?:[a-f0-9]{8})\.([^.]+)$" $1.$2 last;

Development

In your controllers, templates or snippets, import the namespaced helper function and use it with the path to your asset file, relative to the configured assets root.

Depending on the configuration value for fingerprinting, this assets() function returns either the original or the fingerprinted URL to the asset file.

Controller

<?php declare(strict_types=1);

use function Kensho\Assets\asset;

return fn(): array => [
	'stylesheet' => asset(path: 'styles/example.css'),
];

Template or snippet

<?php declare(strict_types=1);

use function Kensho\Assets\asset;
?>
<link rel="stylesheet" href="<?= asset(path: 'styles/example.css') ?>">