PHPackages                             weareferal/file-versioner - 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. [Caching](/categories/caching)
4. /
5. weareferal/file-versioner

ActiveCraft-plugin[Caching](/categories/caching)

weareferal/file-versioner
=========================

Automatically create cache-busting versions of all your files

1.0.0-beta(6y ago)00proprietaryPHPCI failing

Since May 1Pushed 6y agoCompare

[ Source](https://github.com/weareferal/craft-file-versioner)[ Packagist](https://packagist.org/packages/weareferal/file-versioner)[ RSS](/packages/weareferal-file-versioner/feed)WikiDiscussions master Synced 4d ago

READMEChangelog (1)Dependencies (1)Versions (3)Used By (0)

File Versioner
==============

[](#file-versioner)

[![](src/icon.svg)](src/icon.svg)

Automatically generate unique hashed versions of static files and asset files for efficient and reliable browser caching.

Overview
--------

[](#overview)

[![Screenshot overview](resources/img/screenshot-1.jpg)](resources/img/screenshot-1.jpg)

This plugin automatically generates cache-busting hashed versions for both the *static* files within your webroot (JS, CSS, fonts etc.) as well as volume *assets* uploaded by users.

For *static* files, it does this by creating a `scan` command that you can run on every deployment:

```
./craft file-versioner/scan
```

Which can be accessed in your template via a `v` template filter:

```

```

For *asset files*, the versioning happens automatically when a new file is uploaded.

Background
----------

[](#background)

When serving files in production it's common to configure your web server to avail of browser-caching by using the `Cache-Control` header. This instructs the user's browser to keep a local version of a particular file rather than contacting the server. This saves network requests and improves performance.

A common problem with browser-caching arises when a file's content changes. How does the browser know it's changed? If you told the browser to keep that file for 2 week it won't ask for that file again until then, meaning it will continue to have the old stale version.

File versioning is a solution to this. The idea is that you append a hash to the end of the file:

[![](resources/img/asset-versioning-example.png)](resources/img/asset-versioning-example.png)

This means that when the content of the file changes, the hash also changed. When the *hash* changes, the URL changes. This means the user's browser will now always get the latest file, but will still avail of caching when that file remains unchanged.

#### Versioning Challenges

[](#versioning-challenges)

Actually implementing file versioning can be difficult. A website usually has two families of files:

- **Static files**: these are the files used during *development*. Think of them as your 'build-time' files
- **Asset files** these are the files uploaded during *regular usage* by the end-user. Think of them as your 'run-time' files

For static files you *could* manually version them by using a system like `styles.v1.css` `styles.v2.css` etc. but this is tedious and error prone. You could alternatively use your frontend task runner like gulp to do it for you, but this also requires manual intervention.

For asset files there are even less options. You could ask clients to manually version files before uploading them but this is unlikely to be adhered to.

#### Solution

[](#solution)

The solution is to automatically version both static files and asset files. This plugin handles this by offering 'build-time' CLI commands that automatically version static files during deployment as well as transparent 'run-time' processing the automatically versions all user-uploaded assets.

[Read more in our blog post about file versioning](https://weareferal.com/blog/cache-busting-and-asset-versioning-with-craft-cms/)

Requirements
------------

[](#requirements)

This plugin requires Craft CMS 3.0.0 or later.

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

[](#installation)

To install the plugin:

1. Open your terminal and go to your Craft project:

    ```
    $ cd /path/to/project
    ```
2. Then tell Composer to load the plugin:

    ```
    $ composer require weareferal/file-versioner
    ```
3. In the Control Panel, go to Settings → Plugins and click the *Install* button for File Versioner.

Configuration
-------------

[](#configuration)

Copy the example configuration file from the repo `config/file-versioner.example.php` to `config/file-versioner.php` in your project:

```