Skip to main content

version_asset_links.php

This script implements CSS-level cache busting by scanning generated CSS files for asset URLs (like SVG icons) and appending version query parameters based on file modification.

Pathbuild/version_asset_links.php
LanguagePHP
Lines34

Read this when Use this page when tracing PHP asset generation, build hooks, template assembly, or maintenance scripts around version_asset_links.

Overview​

This script implements CSS-level cache busting by scanning generated CSS files for asset URLs (like SVG icons) and appending version query parameters based on file modification times. Unlike build_functions.php which generates versioned URLs for <link> and <script> tags, this script modifies the CSS files themselves to version-stamp URLs they contain.

The script runs during the build pipeline after CSS generation but before final deployment. It reads -GENERATED.css files, identifies asset references (currently just icons.svg), calculates their modification timestamps, performs string replacement to add ?v={timestamp} parameters, and writes the result to -VERSIONED.css files.

This two-stage approach (GENERATED → VERSIONED) ensures that CSS files reference the most current versions of assets they depend on, preventing browser cache staleness when icons or other embedded resources are updated.

Key Operations​

  1. Asset inventory: Builds a map of asset paths to modification times

    • Currently limited to {$icon_dir}/icons.svg
    • Can be extended to other embedded assets

  2. CSS processing: For each target CSS file:

    • Reads the -GENERATED variant
    • Replaces asset URLs with versioned variants
    • Writes to -VERSIONED output file
    • Records output path in $updated_files

  3. Target files:

    • {$css_dir}/head-GENERATED.css → head-VERSIONED.css
    • {$css_dir}/style-GENERATED.css → style-VERSIONED.css

Input/Output​

Input:

  • {$css_dir}/head-GENERATED.css - Generated critical CSS
  • {$css_dir}/style-GENERATED.css - Generated main stylesheet
  • {$icon_dir}/icons.svg - SVG icon sprite (for timestamp)

Output:

  • {$css_dir}/head-VERSIONED.css - CSS with versioned asset URLs
  • {$css_dir}/style-VERSIONED.css - CSS with versioned asset URLs
  • Updates $updated_files array with output paths

Usage​

Invoked by the build system after CSS generation:

php build/version_asset_links.php

Prints: Versioning assets links...

It is invoked by the Git pre-commit hook (pre-commit.hook.php) during the asset pipeline:

# After CSS bundling:
php build/build_unified_assets.php  # Produces *-GENERATED.css files

# Version asset references within CSS:
php build/version_asset_links.php  # Produces *-VERSIONED.css files

# The *-VERSIONED.css files are then referenced by the include builders

The script requires that:

  1. The -GENERATED.css files already exist (produced by earlier build steps)
  2. The asset files being referenced (like icons.svg) exist and are readable
  3. The output directory is writable
See Also