Stop Clients Seeing Old Versions: WordPress Script Caching Explained

Sharing updates with the client is a tale as old as time, but sometimes when you make a change and share a link, they still see the old version of the site.

This is because browsers cache site assets (like images, javascript and css files).

To avoid this problem, we can give each asset a version number ($ver). Both wp_enqueue_script and wp_enqueue_style accept the $ver parameter. This allows you to define a version number and force re-caching of the asset.

For example:

$ver = '1.0.0'; 
wp_enqueue_style('css-main', get_template_directory_uri().'/_output/css/main.css', array(), $ver);

Will generate a script like so:

<link rel="stylesheet" id="css-main-css" href="https://mrcarllister.co.uk/wp-content/themes/base/_output/css/main.css?ver=1.0.0" type="text/css" media="all">

How it started

Working as above, whenever I was building a project I would use something like time()(see https://www.php.net/manual/en/function.time.php for more information on this) in place of a static number. This would generate a unique version number on each page load, each time bypassing caching completely.

<link rel="stylesheet" id="css-main-css" href="https://mrcarllister.co.uk/wp-content/themes/base/_output/css/main.css?ver=1778763631" type="text/css" media="all">

This is fine during development, especially when you’re sharing updates back and forth with a client or other team members as you can guarantee that they’re seeing the most up-to-date version of the site.

First iteration

This isn’t ideal though. Once the project is live, you need to set the $ver parameter to something static to enable caching of that asset (caching might be a pain when rolling out new features but it’s ultimately a good thing for the user experience). This in itself is not a hardship, but on large projects where you can have dozens of scripts and styles, it can be a pain to maintain.

Not to mention when additional functionality is required or you need to make an update to the style of an element, you have to remember to update the $ver number for each affected asset.

My solution

I set a PHP constant with the version number in it:

define('VERSION_NUMBER', '1.0.0.');

Then I reference it on all of my scripts and style assets (note: using a CONSTANT means I can reference this project-wide, a $variable would not allow me to do that):

wp_enqueue_style('css-main', get_template_directory_uri().'/_output/css/main.css', array(), VERSION_NUMBER);

wp_register_script('chartJs', get_template_directory_uri(). '/_dist/js/libs/chart.min.js', array(), VERSION_NUMBER);

wp_register_script('infographicController', get_template_directory_uri(). '/_dist/js/libs/infographicController.min.js', array(), VERSION_NUMBER);

wp_register_script('hoverPanelController', get_template_directory_uri(). '/_dist/js/libs/hoverPanelController.min.js', array(), VERSION_NUMBER);

This worked fine for a long time. In fact, it only really became a problem when I was working on a speed optimisation project for a client. This was when I realised that different environments required different implementation (e.g. I never wanted to cache my local version, but always wanted to cache production).

Final setup

I added an extra step to this functionality: a means to define the environment (in fact, WordPress already has a constant to define this):

define( 'WP_ENVIRONMENT_TYPE', 'LOCAL' );

Defining the working environment as one of LOCAL, DEV, STAGING, or PROD allows me to then also define the VERSION_NUMBER or how the VERSION_NUMBER is generated, on a per-environment basis, like so:

// Set the environment automatically, if not set in wp-config.php
if (!defined('WP_ENVIRONMENT_TYPE')) {
    define('WP_ENVIRONMENT_TYPE', 'LOCAL');
}

// Logic for changing VERSION_NUMBER dependant on environment
switch (WP_ENVIRONMENT_TYPE) {
    case 'PROD':
        $version = '1.0.0';
        break;
    case 'STAGING':
        $version = '1.0.1';
        break;

    default:
        $version = time();
        break;
}

define('VERSION_NUMBER', $version);

The above can go into your functions.php file.

The final step is to make sure that each environments wp-config.php has the WP_ENVIRONMENT_TYPE constant set:

define( 'WP_ENVIRONMENT_TYPE', 'PROD' );

In most installs, the wp-config.php file is not stored within the code repository, making this solution applicable to most projects.

And that’s it!

An easy way to set up environment-based caching rules for assets. This will also hopefully show you the power of constants and their potential for other areas of a project.