All: add jq_url_append_version() (#470)

* Switch from central list to per-url hash.
  This removes the need to know about and remember updating a
  central list. I noticed one file missing already, namely the
  typesense-minibar.js file.

  This slightly improves cache use by not invalidating them
  all together.

* The filemtime timestamp values are so short that an MD5 hash of three
  filemtime() values is actually longer than just the three numbers
  concatenated. This means we lack the benefit a hash usually provides,
  which is that you get exposure to high entropy input in a format
  shorter than that same input.

* Switch from mtime (or mtime-hash) to content-hash.
  This has a few benefits:
  - Note that Git does not track modified times.
    Instead, mtime is whenever a `git clone`, `checkout` or `pull`
    last created or modified the file locally on that server. For
    example, if you `git checkout OLD` and then back to
    `git checkout main`, the files get a newer mtime. This is what
    happens by default at the OS level. Git isn't setting these
    mtime values.

    This means the URL ends up alternating depending on which server
    (e.g. wp-04 and wp-05) last generated the page. It also means
    different pages on the site may have a different URLs for the
    same asset, thus making ineffective use of caching. If the site
    was statically generated in CI, it would bump the cache after every
    commit instead of only when that file has changed, because in CI
    the "git clone" woulld create/modify all files at that time.

  - It is the same between local, staging, and production, which
    might ease debugging in some cases.

  - It allows continuing and re-using old browser (and CDN) caches
    if a commit is rolled back for some reason, since it would
    literally be the same content and thus URL again.

Follows-up 2015fcb.

Ref #469
Ref #468

Co-authored-by: Timmy Willison <[email protected]>

themes/jquery/functions.jquery.php

@@ -185,12 +185,19 @@ function jq_search_get_provider() {
 }
 
 /**
- * Get a checksum of styles used in the header
+ * Try to append a "?v=" cache buster to a static CSS or JS file URI.
  */
-function jq_css_checksum() {
-	$base = get_template_directory() . '/css/base.css';
-	$typesense = get_template_directory() . '/lib/typesense-minibar/typesense-minibar.css';
-	$styles = get_stylesheet_directory() . '/style.css';
+function jq_url_append_version( $uri ) {
+	foreach ( [
+		get_stylesheet_directory_uri() => get_stylesheet_directory(),
+		get_template_directory_uri() => get_template_directory(),
+	] as $uriPrefix => $directory ) {
+		if ( str_starts_with( $uri, $uriPrefix ) ) {
+			$filepath = strtr( $uri, [ $uriPrefix => $directory ] );
+			return $uri . '?v=' . substr( @md5_file( $filepath ) ?: '', 0, 8 );
+		}
+	}
 
-	return md5( filemtime( $base ) . filemtime( $typesense ) . filemtime( $styles ) );
+	// Unchanged
+	return $uri;
 }

themes/jquery/header.php

@@ -17,16 +17,16 @@
 	<meta name="viewport" content="width=device-width">
 
 	<link rel="shortcut icon" href="<?php echo get_stylesheet_directory_uri(); ?>/i/favicon.ico">
-	<link rel="stylesheet" href="<?php echo get_template_directory_uri(); ?>/lib/typesense-minibar/typesense-minibar.css?v=<?php echo jq_css_checksum(); ?>">
-	<link rel="stylesheet" href="<?php echo get_template_directory_uri(); ?>/css/base.css?v=<?php echo jq_css_checksum(); ?>">
-	<link rel="stylesheet" href="<?php bloginfo( 'stylesheet_url' ); ?>?v=<?php echo jq_css_checksum(); ?>">
+	<link rel="stylesheet" href="<?php echo jq_url_append_version( get_template_directory_uri() . '/lib/typesense-minibar/typesense-minibar.css' ); ?>">
+	<link rel="stylesheet" href="<?php echo jq_url_append_version( get_template_directory_uri() . '/css/base.css' ); ?>">
+	<link rel="stylesheet" href="<?php echo jq_url_append_version( get_bloginfo( 'stylesheet_url' ) ); ?>">
 
 	<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
-	<script src="<?php echo get_template_directory_uri(); ?>/js/main.js"></script>
+	<script src="<?php echo jq_url_append_version( get_template_directory_uri() . '/js/main.js' ); ?>"></script>
 <?php
 	if ( jq_search_get_provider() === 'typesense' ) :
 ?>
-	<script defer type="module" src="<?php echo get_template_directory_uri(); ?>/lib/typesense-minibar/typesense-minibar.js?v=<?php echo jq_css_checksum(); ?>"></script>
+	<script defer type="module" src="<?php echo jq_url_append_version( get_template_directory_uri() . '/lib/typesense-minibar/typesense-minibar.js' ); ?>"></script>
 <?php
 	endif;