Multi Source Mapper

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

/**
 * Maps records from multiple source formats into one internal schema.
 *
 * Primary use case: Vendor feeds, migrations, APIs.
 * Typical inputs: source name, source record, mapping registry.
 * Typical output: standard record.
 *
 * Implementation note: Fail loudly on unmapped required fields.
 *
 * @param string $source_name Name of the configured source map.
 * @param array $source_record Incoming source record.
 * @param array $mapping_registry Source mapping rules keyed by source name.
 * @return array Structured mapped-record result.
 */
function ogMapMultiSourceRecord($source_name, $source_record = array(), $mapping_registry = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$source_name = trim((string)$source_name);
	if (empty($source_name)) {
		$result['message'] = 'Source name is required.';
		return $result;
	}

	if (!is_array($source_record)) {
		$result['message'] = 'Source record must be an array.';
		return $result;
	}

	if (!is_array($mapping_registry) || empty($mapping_registry[$source_name]) || !is_array($mapping_registry[$source_name])) {
		$result['message'] = 'Mapping rules were not found for source.';
		return $result;
	}

	$rules = $mapping_registry[$source_name];
	$fields = array();
	if (!empty($rules['fields']) && is_array($rules['fields'])) {
		$fields = $rules['fields'];
	}

	$required = array();
	if (!empty($rules['required']) && is_array($rules['required'])) {
		$required = $rules['required'];
	}

	$mapped = array();
	$missing = array();
	foreach ($fields as $local_field => $source_field) {
		$local_field = (string)$local_field;
		$source_field = (string)$source_field;
		if (array_key_exists($source_field, $source_record)) {
			$mapped[$local_field] = $source_record[$source_field];
		} else {
			$mapped[$local_field] = '';
		}
	}

	foreach ($required as $field) {
		$field = (string)$field;
		if (!array_key_exists($field, $mapped) || trim((string)$mapped[$field]) === '') {
			$missing[] = $field;
		}
	}

	if (!empty($missing)) {
		$result['message'] = 'Required mapped fields are missing.';
		$result['data'] = array('missing_fields' => $missing, 'record' => $mapped);
		return $result;
	}

	$result['success'] = true;
	$result['message'] = 'Source record mapped.';
	$result['data'] = array(
		'source' => $source_name,
		'record' => $mapped
	);

	return $result;
}