https://github.com/bnomei/kirby3-fingerprint
File Method and css/js helper to add hash to files
https://github.com/bnomei/kirby3-fingerprint
cache-buster fingerprint hash kirby3 kirby3-cms kirby3-plugin subresource-integrity
Last synced: 8 months ago
JSON representation
File Method and css/js helper to add hash to files
- Host: GitHub
- URL: https://github.com/bnomei/kirby3-fingerprint
- Owner: bnomei
- License: mit
- Created: 2018-07-24T09:18:35.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T19:29:51.000Z (over 2 years ago)
- Last Synced: 2024-05-01T15:59:06.143Z (over 1 year ago)
- Topics: cache-buster, fingerprint, hash, kirby3, kirby3-cms, kirby3-plugin, subresource-integrity
- Language: PHP
- Homepage: https://forum.getkirby.com/t/kirby-3-fingerprint-asset-cachebuster/23576
- Size: 245 KB
- Stars: 36
- Watchers: 2
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Kirby Fingerprint
[](https://getkirby.com)
[](https://codeclimate.com/github/bnomei/kirby3-fingerprint)
[](https://codeclimate.com/github/bnomei/kirby3-fingerprint/issues)
[](https://discordapp.com/users/bnomei)
[](https://www.buymeacoffee.com/bnomei)
File Method and css/js helper to add a cache busting hash and optional [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) to files.
## Installation
- unzip [master.zip](https://github.com/bnomei/kirby3-fingerprint/archive/master.zip) as folder `site/plugins/kirby3-fingerprint` or
- `git submodule add https://github.com/bnomei/kirby3-fingerprint.git site/plugins/kirby3-fingerprint` or
- `composer require bnomei/kirby3-fingerprint`
## Usage
> [!WARNING]
> This Plugin does **not** override the build in `js()`/`css()` helpers. Use `css_f`/`Bnomei\Fingerprint::css` and `js_f`/`Bnomei\Fingerprint::js` when you need them.
```php
echo css_f('/assets/css/index.css');
echo Bnomei\Fingerprint::css('/assets/css/index.css');
// element with https://../assets/css/index.css?v=1203291283
echo js_f('/assets/js/index.min.js');
echo Bnomei\Fingerprint::js('/assets/js/index.min.js');
// <link> element https://../assets/js/index.min.js?v=1203291283
echo url_f('/assets/css/index.css');
echo Bnomei\Fingerprint::url('/assets/css/index.css');
// raw url https://../assets/css/index.css?v=1203291283
echo $page->file('ukulele.pdf')->fingerprint();
// https://../ukulele.pdf?v=1203291283
echo $page->file('ukulele.pdf')->integrity();
// sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC
// generate sri from local file
echo Bnomei\Fingerprint::js(
'/assets/js/index.min.js',
[
"integrity" => true
]
);
/*
<script src="https://../assets/js/index.min.js"
integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
crossorigin="anonymous"></script>
*/
echo Bnomei\Fingerprint::js(
'https://external.cdn/framework.min.js',
[
"integrity" => "sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
]
);
/*
<script src="https://external.cdn/framework.min.js"
integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
crossorigin="anonymous"></script>
*/
```
## Cache
> [!WARNING]
> If **global** debug mode is `true,` the plugin will flush its cache and not write any more caches.
Hash and SRI values are cached and only updated when the original file is modified.
For best performance, set either the [global or plugin-specific cache driver](https://getkirby.com/docs/reference/system/options/cache) to one using the server's memory, not the default using files on the hard disk (even on SSDs). If available, I suggest Redis/APCu or leave it at `file` otherwise.
**site/config/config.php**
```php
return [
'cache' => [
'driver' => 'apcu', // or redis
],
'bnomei.fingerprint.cache' => [
'type' => 'apcu', // or redis
],
];
```
## Similar Plugins
The following plugins can do cache busting, but they do not cache the modified timestamp, nor can they do SRI, nor do cache busting for non-js/CSS files.
- [bvdputte/kirby-fingerprint](https://github.com/bvdputte/kirby-fingerprint)
- [schnti/kirby3-cachebuster](https://github.com/schnti/kirby3-cachebuster)
- [diverently/laravel-mix-kirby](https://github.com/diverently/laravel-mix-kirby)
## Settings
| bnomei.fingerprint. | Default | Description |
|---------------------------|----------------|-------------------------------------------------------------------------------------|
| hash | `callback` | will lead to the hashing logic |
| integrity | `callback` | use it to set option `'integrity' => null,` |
| digest | `'sha384'` | Cryptographic digest to be used for SRI hashes either `'sha256'`, `'sha384'` or `'sha512'`. |
| https | `true` | boolean value or callback to force *https* scheme on all but localhost enviroments. |
| query | `true` or `string` or `callback` | `myfile.js?v={HASH}`, `myfile.{HASH}.js` or loaded from manifest file |
### Query option: true (default)
```
myfile.js?v={HASH}
```
This is the default since it works without additional changes to your server but be aware that [query strings are not perfect](http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/).
### Query option: false
If you disable the query option, you also need to add Apache or Nginx rules. These rules will redirect CSS and JS files from with hash to the asset on disk.
**.htaccess** - put this directly after the `RewriteBase` statment
```apacheconfig
# RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.+)\.([0-9a-z]{32})\.(js|css)$ $1.$3 [L]
```
**Nginx virtual host setup**
```
location ~ (.+)\.(?:\w+)\.(js|css)$ {
try_files $uri $1.$2;
}
```
### Query option: string (Manifest files)
You can also forward the path of a JSON-encoded manifest file, and the plugin will load whatever hash is defined there. This works great for [gulp-rev](https://github.com/sindresorhus/gulp-rev) or with [laravel mix versioning](https://laravel-mix.com/docs/master/versioning).
## Disclaimer
This plugin is provided "as is" with no guarantee. You can use it at your own risk and always test it before using it in a production environment. If you find any issues, please [create a new issue](https://github.com/bnomei/kirby3-fingerprint/issues/new).
## License
[MIT](https://opensource.org/licenses/MIT)
It is discouraged to use this plugin in any project that promotes racism, sexism, homophobia, animal abuse, violence or any other form of hate speech.
## Credits
- based on [@iksi](https://github.com/iksi) https://github.com/iksi/kirby-fingerprint (Kirby V2)
- [@S1SYPHOS](https://github.com/S1SYPHOS) https://github.com/S1SYPHOS/kirby-sri (Kirby V2)