Skip to content
Home
← Back to Functions
Code

Fragment Cache Key Builder

Builds stable cache keys from route, user visibility, locale, and query state.

Function signature

ogBuildFragmentCacheKey(route_data = array(), context = array(), version_salt = 'v1')

Categories

  • Forms and Validation

Parameters

route_dataRoute context used to build breadcrumbs or cache keys.contextRuntime context used for feature, cache, or debug decisions.version_saltVersion string used to invalidate old fragment-cache keys deliberately.

Return value

Public-safe status string returned by the function for explicit controller branching or logging.

  • success
  • message
  • data

Compatibility

Existing function name, slug, path, and call order preserved; advertised metadata corrected to the actual source behavior.

Minimum PHP version: 7.4

Security notes

Use caller-owned allowlists and context-specific escaping; validate admin actions, export fields, privacy plans, cache keys, templates, settings, routes, and ecommerce policies before production use.

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.
 */

/**
 * Builds a stable cache key for a route, visibility context, locale, and version salt.
 *
 * Sensitive values are not included directly. Variable context is normalized and hashed.
 *
 * @param array $route_data Route/page data.
 * @param array $context Visibility, locale, query, and role context.
 * @param string $version_salt Cache version salt.
 * @return array Cache key result.
 */
function ogBuildFragmentCacheKey($route_data = array(), $context = array(), $version_salt = 'v1') {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($route_data)) {
		$route_data = array();
	}
	if (!is_array($context)) {
		$context = array();
	}

	$parts = array();
	$allowed_route_keys = array('route', 'section', 'id', 'slug', 'page');
	foreach ($allowed_route_keys as $key) {
		if (!empty($route_data[$key]) || $route_data[$key] === 0) {
			$parts[] = $key . ':' . preg_replace('/[^a-zA-Z0-9_.-]/', '-', (string)$route_data[$key]);
		}
	}

	$visibility = 'public';
	if (!empty($context['visibility'])) {
		$visibility = preg_replace('/[^a-zA-Z0-9_.-]/', '-', (string)$context['visibility']);
	}
	$locale = 'en-US';
	if (!empty($context['locale'])) {
		$locale = preg_replace('/[^a-zA-Z0-9_.-]/', '-', (string)$context['locale']);
	}

	$query_hash = '';
	if (!empty($context['query']) && is_array($context['query'])) {
		ksort($context['query']);
		$query_hash = hash('sha256', json_encode($context['query']));
	}

	$version_salt = preg_replace('/[^a-zA-Z0-9_.-]/', '-', (string)$version_salt);
	$base = implode('|', $parts) . '|visibility:' . $visibility . '|locale:' . $locale . '|query:' . $query_hash . '|version:' . $version_salt;
	$key = 'phpog_fragment_' . substr(hash('sha256', $base), 0, 40);

	$result['success'] = true;
	$result['message'] = 'Fragment cache key built.';
	$result['data'] = array(
		'cache_key' => $key,
		'base_hash' => hash('sha256', $base)
	);

	return $result;
}