README

Twig Cache Busting is an add-on for Twig to support cache busting on template compilation.

Installation

$ composer require adriansuter/twig-cache-busting

Description

This add-on would extend Twig by a cache busting mechanism. The cache busting is taking place upon compilation of the template (not upon rendering). So whenever you update an asset, you would need to recompile the templates that reference this asset (or clear the cache and let Twig rebuild it automatically). The benefit is, that if you cache your compiled templates, then the server would process the performance intense cache busting only once (not on every request).

Cache Busters

By default, there are three cache busting methods. But you can develop your own custom cache buster by implementing the \AdrianSuter\TwigCacheBusting\Interfaces\CacheBusterInterface.

Query Param Cache Buster This cache buster would append a query param to the file path. So an asset with the path image.jpg gets transformed for example to image.jpg?c=abcd.
File Name Cache Buster This cache buster would alter the file name. So an asset with the path image.jpg gets transformed for example to image.abcd.jpg.
Dictionary Cache Buster This cache buster would use a lookup table (map) to find the target file path.

Hash Generators

The Query Param Cache Buster and the File Name Cache Buster both use a hash generator to generate a hash for the given asset (in the examples above, the hash is abcd). By default the following hash generators are possible. But you can develop your own custom hash generator by implementing \AdrianSuter\TwigCacheBusting\Interfaces\HashGeneratorInterface.

FileMD5HashGenerator This hash generator calculates the MD5 hash of the file.
FileSHA1HashGenerator This hash generator calculates the SHA1 hash of the file.
FileModificationTimeHashGenerator This hash generator uses the file modification time as Unix timestamp.

Usage

Query Param Cache Buster

Assume you have a file /home/htdocs/public/assets/image.jpg and your template is as follows:

<img src="{% cache_busting 'assets/image.jpg' %}">

To use the Query Param Cache Buster you need to pass the QueryParamCacheBuster to the static create method of the CacheBustingTwigExtension.

use AdrianSuter\TwigCacheBusting\CacheBusters\QueryParamCacheBuster;
use AdrianSuter\TwigCacheBusting\CacheBustingTwigExtension;

//...

$twig->addExtension(
    CacheBustingTwigExtension::create(
        new QueryParamCacheBuster('/home/htdocs/public')
    )
);

By default, the QueryParamCacheBuster uses the FileModificationTimeHashGenerator. But you can set another generator by passing a second argument to the constructor. For example:

use AdrianSuter\TwigCacheBusting\HashGenerators\FileMD5HashGenerator;

new QueryParamCacheBuster('/home/htdocs/public', new FileMD5HashGenerator())

File Name Cache Buster

Assume you have a file /home/htdocs/public/assets/image.jpg and your template is as follows:

<img src="{% cache_busting 'assets/image.jpg' %}">

To use the File Name Cache Buster you need to pass the FileNameCacheBuster to the static create method of the CacheBustingTwigExtension.

use AdrianSuter\TwigCacheBusting\CacheBusters\FileNameCacheBuster;
use AdrianSuter\TwigCacheBusting\CacheBustingTwigExtension;

// ...

$twig->addExtension(
    CacheBustingTwigExtension::create(
        new FileNameCacheBuster('/home/htdocs/public')
    )
);

Your web server needs to be configured such that the cache busting requests get redirected. For Apache you would need to set

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.+)\.(\d+)\.(js|css|jpg|png|svg)$ $1.$3 [L]

Note that you might want to add more extensions to the rewrite rule.

By default, the FileNameCacheBuster uses the FileModificationTimeHashGenerator. But you can set another generator by passing a second argument to the constructor. For example:

use AdrianSuter\TwigCacheBusting\HashGenerators\FileMD5HashGenerator;

new FileNameCacheBuster('/home/htdocs/public', new FileMD5HashGenerator())

If your hash generator returns hexadecimal hashes, then you would need to adapt the Apache rewrite rule appropriately. For example:

RewriteRule ^(.+)\.([a-f0-9]+)\.(js|css|jpg|png)$ $1.$3 [L]

Dictionary Cache Buster

This cache busting method would use a dictionary to lookup file names. The dictionary is basically a mapping between the original file path and the cache busting version.

use AdrianSuter\TwigCacheBusting\CacheBusters\DictionaryCacheBuster;
use AdrianSuter\TwigCacheBusting\CacheBustingTwigExtension;
use AdrianSuter\TwigCacheBusting\Dictionaries\ArrayDictionary;

// ...

$twig->addExtension(
    CacheBustingTwigExtension::create(
		new DictionaryCacheBuster(
			new ArrayDictionary([
				'assets/image.jpg' => 'assets/cb-1c2d7c4s36d47d.jpg',
			])
		)
	)
);

Base Path

If you want to prepend a base path to the generated paths, then simply pass that to the static create method of the CacheBustingTwigExtension. For example:

$twig->addExtension(
    CacheBustingTwigExtension::create(
        new QueryParamCacheBuster('/home/htdocs/public'),
        'base-path'
    )
);

Custom Twig Tag

If you want to change the twig tag cache_busting into something else, you can do that simply by setting the third argument of the static create method of the CacheBustingTwigExtension. For example:

$twig->addExtension(
    CacheBustingTwigExtension::create(
        new QueryParamCacheBuster('/home/htdocs/public'),
        null,
        'cb'
    )
);

Now you can use cb in your templates in order to apply cache busting.

<img src="{% cb 'assets/image.jpg' %}">

Contribution

Is much welcomed.

adriansuter / twig-cache-busting

Maintainers

Details