CSS Cache Busting in WordPress using a query string with a timestamp of the stylesheet lastmod value
Take this scenario: you made 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.
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
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
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,
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.
- November 11, 2019
- Referenced Steve Sounders’ suggestion for revving by changing the filename rather than by appending a query string.
Email me at firstname.lastname@example.org.