Lookup Cache 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 a keyed lookup array from database rows or other records.
 *
 * @param array $rows Source records.
 * @param string $key_field Field used as the lookup key.
 * @param array $value_fields Optional fields to keep in each lookup value.
 * @return array Lookup cache result.
 */
function ogBuildLookupCache($rows = array(), $key_field = 'id', $value_fields = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($rows)) {
		$result['message'] = 'Rows must be supplied as an array.';
		return $result;
	}

	$key_field = trim((string)$key_field);
	if (empty($key_field)) {
		$result['message'] = 'Key field is required.';
		return $result;
	}

	$lookup = array();
	$duplicates = array();
	foreach ($rows as $row) {
		if (!is_array($row) || !array_key_exists($key_field, $row)) {
			continue;
		}
		$key = (string)$row[$key_field];
		if (array_key_exists($key, $lookup)) {
			$duplicates[] = $key;
		}

		if (empty($value_fields)) {
			$lookup[$key] = $row;
		} else {
			$value = array();
			foreach ($value_fields as $field) {
				$field = (string)$field;
				if (array_key_exists($field, $row)) {
					$value[$field] = $row[$field];
				}
			}
			$lookup[$key] = $value;
		}
	}

	$result['success'] = true;
	$result['message'] = 'Lookup cache built.';
	$result['data'] = array(
		'lookup' => $lookup,
		'count' => count($lookup),
		'duplicates' => $duplicates
	);

	return $result;
}