Browser caching is a wonderful thing. It helps web pages load faster by temporarily storing a copy of assets (images, CSS, etc.) on your computer/device instead of re-downloading on every subsequent page load. However, this caching can be a minor annoyance during theme development. Inevitably you'll update some CSS and your customer will say they don't see the change. This is because they don't have the most recent CSS - they're viewing an outdated, cached copy.

A common approach to avoid this issue is to append a query string to asset URLs. For example, changing main.css?version=1 to main.css?version=2 typically triggers browsers to download a fresh copy because it's a different URL. Another, more robust, route is to change the filename of each asset like main.2.css (often using the "filename-based cache busting" technique discussed in the HTML5 Boilerplate .htaccess config).

Having a solution is fantastic, but remembering to continually update this number can be annoying during development.

Recently, it hit us that we could take advantage of our common site.php config and have PHP do the work for us. The idea is to use PHP's time() function to generate this new version number on every page load in our dev and staging environments (asset caching isn't usually that important for us there). On live/production sites (where caching is very important and we want full control), we continue to do manual version bumps.

Step 1: Define a Version Number

To accomplish this, we define a constant CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER in our /site/config.php.

<?php
/* SERVER SPECIFIC VARS
----------------------------------------------------*/
    /*** LOCAL ***/
    if (strpos($_SERVER['SERVER_NAME'], 'localhost') !== false) {
        define('CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER', time());
    /*** STAGE ***/
    } else if (strpos($_SERVER['SERVER_NAME'], '.myagency.com') !== false) {
        define('CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER', time());
	/*** PRODUCTION ***/
	} else {
        define('CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER', '2');
	}

Step 2: Add the number to all assets that need it

Whenever we reference an asset, we just echo the CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER. For instance, our main CSS file would look like this if we used the query string approach:

<link rel="stylesheet" type="text/css" href="<?php echo $this->getThemePath(); ?>/css/main.css?version=<?php echo CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER; ?>" />

Or like this if we used the filename-based cache busting approach:

<link rel="stylesheet" type="text/css" href="<?php echo $this->getThemePath(); ?>/css/main.<?php echo CUSTOM_THEME_ASSET_CACHE_BUST_NUMBER; ?>.css" />

You can use this for any images, CSS, or JavaScript you include in your theme's HTML/PHP.

While a pretty minor trick, we've found it quite refreshing to completely forget about browser caching issues and focus on the work at hand during development.