Skip to content

Latest commit

 

History

History
165 lines (99 loc) · 5.61 KB

readme.md

File metadata and controls

165 lines (99 loc) · 5.61 KB
Raw

Cache Buster

A Craft plugin that helps keep your front-end assets free of cache issues after they've changed.

Installation

  • Move the cachebuster directory into your project's craft/plugins directory.
  • Navigate to Settings > Plugins page in your Craft admin area and install Cache Buster.
  • Rejoice that installation is simple.

Using the Cache Buster Plugin

There are a few ways you can use this plugin. At it's simplest, you can just pass your asset files through Twig and a cache busting query string will magically appear. That's it. No setup. If that sounds good look at the Auto Query String section below.

If you'd like to use a single query string to bust your cache, you'll want to use the Manual Query String section below. This is useful if you want to use something a commit hash (or substring) for all of your cache busting.

Lastly, if you already rev your files before deploying them, you can check out the Revved Files Manifest section below. This is the recommended route, but only if you kinda already know what it means. (Click here to learn a bit about it.)

Auto Query String

You have 3 options for creating cache busting file paths. They're all the same result. It's just a matter of which style you prefer. They are:

The Craft Variable

{{ craft.cacheBuster.bust('/css/site.css') }}

The Twig Filter

{{ '/css/site.css' | cacheBuster }}

The Twig Function

{{ cacheBuster('/css/site.css') }}

These will all return something like

/css/site.css?v=1472591574

Where 1472591574 is the UNIX timestamp of the last time /css/site.css was saved to the server.

Options

You can change the separator between the file and the timestamp by passing an argument through any of these code examples. They would then respectively look something like this:

{{ craft.cacheBuster.bust('/css/site.css', 'bustIt=') }}

{{ '/css/site.css' | cacheBuster('bustIt=') }}

{{ cacheBuster('/css/site.css', 'bustIt=') }}

These will all return something like

/css/site.css?bustIt=1472591574

Manual Query String

To configure Cache Buster to use the same query string for all cache busting, you just need to add a simple config item to your setup.

  1. Use the same exact Twig tags mentioned in the Simple Query String section above
  2. Create a new file called craft/config/cachebuster.php
  3. Return an array with the key queryString
  4. That's it!

Your config file might look something like this:

<?php

return array(
	'queryString' => 'ad7f89'
);

You can also adjust this config file to support multiple environments in the same way you might do so with your Craft config.

Revved Files Manifest

This is the best option in terms of loading time. It takes a bit more setup and we (Focus Lab) don't intend to support your learning curve in terms of revving files as a whole. For that you can use the trusty Google and Stack Overflow.

Assuming you already have files being revved, and are generating some type of manifest json of your files, you will want to do the following:

  1. Use the same exact Twig tags mentioned in the Simple Query String section above
  2. Create a new file called craft/config/cachebuster.php
  3. Return an array with the key assetManifest and a value pointing to your .json file
  4. That's it!

Your config file might look something like this:

<?php

return array(
	'assetManifest' => 'assets/assetManifest.json'
);

Important: Cache Buster assumes the assetManifest path will start at the same directory level as your craft directory. In the example above, assets is a sibling directory to craft on server.

Cache Buster uses the name of your original file as the key when using a manifest json object. So if your original working front-end file is located at /css/site.css your manifest would include it like this:

{
	"/css/site.css": "/css/site.12345.css"
}

And you would reference this in your front-end with one of the three samples from the Simple Query String section.

{{ craft.cacheBuster.bust('/css/site.css') }}

{{ '/css/site.css' | cacheBuster }}

{{ cacheBuster('/css/site.css') }}

Each of these will respect your manifest. If for any reason Cache Buster can't find a key matching the file provided in the template, it moves to the Manual Query String option. If you haven't defined a queryString config setting, then Cache Buster falls back to the Auto Query String method.

So no matter what you get a cache busted asset served.

Debugging

If you're not getting the result you experience, start by checking the Cache Buster log file. You can find it in craft/storage/runtime/logs/cachebuster.log or by viewing it in the Admin area at /admin/utils/logs/cachebuster.log.

This file will only exist if specific errors have occurred while using Cache Buster.

Change Log

Nov 16th, 2016: 1.2.2

  • Added new error logging for the query string cache busting method.

Sept 27th, 2016: 1.2.1

  • Added the ability to prefix an asset string globally or individually

Sept 6th, 2016: 1.1.1

  • Added some smarter logic around handling asset manifest keys.

Sept 5th, 2016: 1.1.0

  • Added support for flat file manifests for those revving files. No query string needed with this approach.
  • Added support for using a consistent query string for all cache busting (like a git commit hash/substring).

Sept 3rd, 2016: 1.0.0

  • Initial Release