Cache Warmup Plan Builder

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 an ordered cache warmup plan from route rows or URL rows.
 *
 * Only local paths and protocol-relative site URLs are accepted by default.
 *
 * @param array $routes Routes or URL rows to warm.
 * @param array $options Warmup options.
 * @return array Ordered warmup plan.
 */
function ogBuildCacheWarmupPlan($routes = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($routes)) {
		$result['message'] = 'Routes must be an array.';
		return $result;
	}
	if (!is_array($options)) {
		$options = array();
	}

	$limit = 100;
	if (!empty($options['limit'])) {
		$limit = (int)$options['limit'];
	}
	if ($limit < 1) {
		$limit = 1;
	}

	$host = 'phpog.com';
	if (!empty($options['host'])) {
		$host = preg_replace('/^www\./i', '', trim((string)$options['host']));
	}

	$plan = array();
	$seen = array();
	$warnings = array();
	foreach ($routes as $route) {
		$url = '';
		$priority = 50;
		if (is_array($route)) {
			if (!empty($route['url'])) {
				$url = trim((string)$route['url']);
			}
			if (!empty($route['priority'])) {
				$priority = (int)$route['priority'];
			}
		} else {
			$url = trim((string)$route);
		}

		if (empty($url)) {
			continue;
		}
		if (strpos($url, '//') === 0) {
			if (stripos($url, '//' . $host . '/') !== 0) {
				$warnings[] = 'Skipped external URL: ' . $url;
				continue;
			}
		} elseif (substr($url, 0, 1) != '/') {
			$warnings[] = 'Skipped non-local URL: ' . $url;
			continue;
		}

		if (!empty($seen[$url])) {
			continue;
		}
		$seen[$url] = true;
		$plan[] = array(
			'url' => $url,
			'priority' => $priority
		);
	}

	$swap_count = 1;
	while ($swap_count > 0) {
		$swap_count = 0;
		for ($i = 0; $i < count($plan) - 1; $i++) {
			$swap = false;
			if ($plan[$i]['priority'] < $plan[$i + 1]['priority']) {
				$swap = true;
			} elseif ($plan[$i]['priority'] == $plan[$i + 1]['priority']) {
				if (strcmp($plan[$i]['url'], $plan[$i + 1]['url']) > 0) {
					$swap = true;
				}
			}
			if ($swap) {
				$temp = $plan[$i];
				$plan[$i] = $plan[$i + 1];
				$plan[$i + 1] = $temp;
				$swap_count++;
			}
		}
	}
	$plan = array_slice($plan, 0, $limit);

	$result['success'] = true;
	$result['message'] = 'Cache warmup plan built.';
	$result['data'] = array(
		'plan' => $plan,
		'warnings' => $warnings,
		'count' => count($plan)
	);

	return $result;
}