Asset Version Manifest

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Creates a version map for CSS, JS, image, and font assets.
 *
 * Primary use case: Cache busting.
 * Typical inputs: asset paths, hashing option.
 * Typical output: manifest array.
 *
 * Implementation note: Use filemtime or hashes; avoid query strings if SEF policy forbids them.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogBuildAssetVersionManifest($base_path, $asset_paths = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$base_path = (string)$base_path;
	if (!is_array($asset_paths)) {
		$result['message'] = 'Asset paths must be an array.';
		return $result;
	}
	if (!is_array($options)) {
		$options = array();
	}

	$base_real = realpath($base_path);
	if ($base_real === false || !is_dir($base_real)) {
		$result['message'] = 'Asset base path is invalid.';
		return $result;
	}

	$use_hash = false;
	if (!empty($options['use_hash']) && $options['use_hash'] === true) {
		$use_hash = true;
	}

	$manifest = array();
	$missing = array();
	foreach ($asset_paths as $asset_path) {
		$asset_path = '/' . ltrim((string)$asset_path, '/');
		$local_path = $base_real . str_replace('/', DIRECTORY_SEPARATOR, $asset_path);
		$real_path = realpath($local_path);
		if ($real_path === false || strpos($real_path, $base_real) !== 0 || !is_file($real_path)) {
			$missing[] = $asset_path;
			continue;
		}

		$version = (string)filemtime($real_path);
		if ($use_hash) {
			$hash = hash_file('sha256', $real_path);
			if ($hash !== false) {
				$version = substr($hash, 0, 16);
			}
		}

		$manifest[$asset_path] = array(
			'path' => $asset_path,
			'version' => $version,
			'bytes' => filesize($real_path)
		);
	}

	$result['success'] = true;
	$result['message'] = 'Asset version manifest built.';
	$result['data'] = array(
		'manifest' => $manifest,
		'missing' => $missing
	);

	return $result;
}