nikrolls/ss-hashpath-manifest

dev-master 2020-10-29 08:34 UTC

Requires

• silverstripe/framework: 4.*

Requires (Dev)

• phpunit/phpunit: ^5.7

MIT

• Nik Rolls

README

Inspired by heyday/silverstripe-hashpath, this module is designed for statically published sites that don't have an active server component to rewwrite the hash paths on the fly. It's designed to work with the manifest files generated by tools such as gulp-hash which hash the filenames at build time and generate a JSON manifest of path resolutions.

Installation

Using composer:

$ composer require nikrolls/ss-hashpath-manifest

Usage

Prerequisites

This module makes a few assumptions:

1. That the JSON manifest file is in the same folder as the hashed files, or any ancestor folder
2. That all paths in the manifest file are relative to the location of the manifest file
3. That the manifest file is in charge of all hashed files in its folder and any child folders

Configuration

Create a yaml config file like below:

NikRolls\SSHashPathManifest\HashPath:
  manifests:
    themes/default: manifest.json
# Add more root paths and relative manifest paths as required, eg:
#   themes/alternate/build: output/manifest.json
#   themes/alternate: source/manifest.json
# More specific paths should be first as the first matching one found is used.

themes/default/manifest.json:

{
  "js/main.js": "js/main.abcd1234.js",
  "css/main.css": "css/main.4321dcba.css"
}

Implementation

You can translate the paths either in a Requirements call, or in a template:

use NikRolls\SSHashPathManifest\HashPath;

Requirements::javascript(HashPath::singleton()->for('themes/default/js/main.js'));

<script src="resources/$HashPath('themes/default/js/main.js')"></script>

The module does little more than translate paths according to the manifest file, so if you have resource prefixes in your statically published environment, simply prepend them to your paths.

If there is no manifest found for your path, or a manifest was found but doesn't contain the file you're requesting, the path will be returned unchanged. This allows you to use HashPath for every file within a build folder but control the path resolution (or not) with your build process, for example.