CSS Cache Busting in WordPress using a query string with a timestamp of the stylesheet lastmod value

Take this scenario: you make changes to a stylesheet while developing a WordPress theme, reload the browser window and don't see your changes. You view the rendered source code and see that the browser is still loading the old version of the file. You check that you are editing the correct file, in the correct place. You empty the browser cache and reload and its still the same (or maybe—maybe—that did the trick, but you can't ask your site visitors to do that). Somewhere along the line the stylesheet is getting cached and you need to make sure that when the site is loaded the new version of the stylesheet is loaded along with it.

The best method to address this, in or out of WordPress, is to version the stylesheet, that is, to change the filename (which is the very best method according to Steve Sounders, author of High Performance Websites, who did the research) or, if you are unable to do that, to add a query string to the end. Since style.css is a requirement of the theme, the filename cannot be changed, however, adding a query string is a viable option.

As a side note, a totally unrelated method of addressing this would be to avoid using the style.css file for anything other than setting up the theme which would open up file renaming possibilities, but that is a matter for another time.

A query string takes the form of a question mark followed by the field name, an equals sign for assignment, and the value: ?ver=foo. It doesn't matter what the field name or value are for our purposes. The example uses ver as an abbreviation of version for the field name. The value could be a random looking string (e.g. 12345678) or a thought out version number, perhaps tied to the WordPress theme version (e.g. 3.2.6).

How that version string is appended to the stylesheet is a function of WordPress's wp_enqueue_style() function. Since WordPress Version 2.6, the wp_enqueue_style() function has an optional parameter for "version". When set, a query string is added to the URL for the stylesheet, e.g. ?ver=foo which should indicate to the browser that style.css?ver=foo is different than style.css?ver=bar or, without any version query string at all, style.css, and cause it to load style.css?ver=foo.

The version value can be set manually during the call to the function, here being set to 1.0.1 (note the 3rd argument is an empty array() which is the default argument for $deps):

wp_enqueue_style('main_css', get_template_directory_uri() . '/style.css', array(), '1.0.1');

The problem with the manual versioning is that every time the stylesheet file is changed, the version has to be updated in the functions.php file. This isn't necessarily easy to remember or a good use of development time. An alternative method is to dynamically create a version value based on the time the stylesheet was last modified using PHP's filetime() function which returns that time of last modification as a value measured in the number of seconds since the Unix Epoch. For example, 1568061612.

To implement this method, in the WordPress Theme's functions.php, update the wp_enqueue_style() function as follows:

wp_enqueue_style( 
    'main_css', 
    get_template_directory_uri() . '/style.css', 
    array(), 
    filemtime( get_stylesheet_directory() . '/style.css' )
);

The method of cache busting by using a timestamp goes back at least to 2008 when Chris Coyier cited it and is reasonably reliable. Using the file's timestamp is a more efficient method than creating a random string or the original current time method Chris cites, as it won't change every time the function or page is called.

Revisions

November 11, 2019

Referenced Steve Sounders’ suggestion for revving by changing the filename rather than by appending a query string.

Feedback?

Email us at enquiries@kinsa.cc.