PHPackages                             adriansuter/twig-cache-busting - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. adriansuter/twig-cache-busting

ActiveLibrary[Templating & Views](/categories/templating)

adriansuter/twig-cache-busting
==============================

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

4.0(5mo ago)45.3k↓50%1MITPHPPHP >=8.2CI passing

Since Sep 18Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/adriansuter/Twig-Cache-Busting)[ Packagist](https://packagist.org/packages/adriansuter/twig-cache-busting)[ RSS](/packages/adriansuter-twig-cache-busting/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (12)Used By (0)

Twig-Cache-Busting
==================

[](#twig-cache-busting)

[![Build Status](https://github.com/adriansuter/Twig-Cache-Busting/workflows/Tests/badge.svg?branch=master)](https://github.com/adriansuter/Twig-Cache-Busting/actions?query=branch:master)[![Coverage Status](https://camo.githubusercontent.com/5eef3b0150236e695cc3eca70c1359c1c72a710e3e4948cd7239cf606cf0caac/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f61647269616e73757465722f547769672d43616368652d42757374696e672f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/adriansuter/Twig-Cache-Busting?branch=master)[![Total Downloads](https://camo.githubusercontent.com/895afc1e590199eb55e7bf18a4dc32a67da9763528e6f3d8ed87a47aa783a915/68747470733a2f2f706f7365722e707567782e6f72672f61647269616e73757465722f747769672d63616368652d62757374696e672f646f776e6c6f616473)](https://packagist.org/packages/adriansuter/twig-cache-busting)[![License](https://camo.githubusercontent.com/1d874c1e1121f89618a9af9bbf0efbd042366424d859220c0d67537707872a4e/68747470733a2f2f706f7365722e707567782e6f72672f61647269616e73757465722f747769672d63616368652d62757374696e672f6c6963656e7365)](https://packagist.org/packages/adriansuter/twig-cache-busting)

Twig Cache Busting is an add-on for [Twig](https://twig.symfony.com/) to support cache busting on **template compilation**.

Installation
------------

[](#installation)

```
$ composer require adriansuter/twig-cache-busting
```

Description
-----------

[](#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

[](#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

[](#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
-----

[](#usage)

### Query Param Cache Buster

[](#query-param-cache-buster)

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

```

```

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

[](#file-name-cache-buster)

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

```

```

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

[](#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
---------

[](#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
---------------

[](#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.

```

```

Contribution
------------

[](#contribution)

Is much welcomed.

###  Health Score

51

—

FairBetter than 96% of packages

Maintenance71

Regular maintenance activity

Popularity26

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 89.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~251 days

Recently: every ~428 days

Total

10

Last Release

165d ago

Major Versions

0.2 → 1.02019-10-31

1.3 → 2.02022-11-09

2.0 → 3.02023-01-18

3.1 → 4.02025-12-03

PHP version history (5 changes)0.1PHP ^7.1

1.3PHP ^7.1 || ^8

2.0PHP ^7.3 || ^8

3.0PHP ^8

4.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/4ff41e3338b4e847e43441cf54099844bae3c789b409a378f8f6374d37ba1057?d=identicon)[adriansuter](/maintainers/adriansuter)

---

Top Contributors

[![adriansuter](https://avatars.githubusercontent.com/u/3974990?v=4)](https://github.com/adriansuter "adriansuter (59 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (5 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![maddmages-l2lnch](https://avatars.githubusercontent.com/u/257162407?v=4)](https://github.com/maddmages-l2lnch "maddmages-l2lnch (1 commits)")

---

Tags

cache-busterscache-bustingtwigtwig-extensiontwigcachecache-busting

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/adriansuter-twig-cache-busting/health.svg)

```
[![Health](https://phpackages.com/badges/adriansuter-twig-cache-busting/health.svg)](https://phpackages.com/packages/adriansuter-twig-cache-busting)
```

###  Alternatives

[twig/extra-bundle

A Symfony bundle for extra Twig extensions

91292.0M315](/packages/twig-extra-bundle)[twig/intl-extra

A Twig extension for Intl

36663.2M221](/packages/twig-intl-extra)[rcrowe/twigbridge

Adds the power of Twig to Laravel

9105.9M50](/packages/rcrowe-twigbridge)[twig/string-extra

A Twig extension for Symfony String

21946.0M133](/packages/twig-string-extra)[twig/cssinliner-extra

A Twig extension to allow inlining CSS

23018.5M55](/packages/twig-cssinliner-extra)[symfony/ux-twig-component

Twig components for Symfony

21814.8M162](/packages/symfony-ux-twig-component)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)