API Field 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 external API fields into local field names with type conversion.
 *
 * Mapping rules are explicit and allowlisted. Required local fields are checked after mapping so
 * failed integrations produce useful import errors.
 *
 * @param array $external_record External API record.
 * @param array $mapping_rules Field mapping and type rules.
 * @return array Local mapped record and validation messages.
 */
function ogMapApiFieldsToLocal($external_record = array(), $mapping_rules = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($external_record)) {
		$result['message'] = 'External record must be an array.';
		return $result;
	}
	if (!is_array($mapping_rules)) {
		$result['message'] = 'Mapping rules must be an array.';
		return $result;
	}

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

	$local = array();
	$warnings = array();
	foreach ($fields as $local_field => $rule) {
		$local_field = preg_replace('/[^a-zA-Z0-9_]/', '', (string)$local_field);
		if (empty($local_field)) {
			continue;
		}
		$source_field = '';
		$type = 'string';
		$default = '';
		if (is_array($rule)) {
			if (!empty($rule['source'])) {
				$source_field = (string)$rule['source'];
			}
			if (!empty($rule['type'])) {
				$type = (string)$rule['type'];
			}
			if (array_key_exists('default', $rule)) {
				$default = $rule['default'];
			}
		} else {
			$source_field = (string)$rule;
		}
		$value = $default;
		if (array_key_exists($source_field, $external_record)) {
			$value = $external_record[$source_field];
		}
		if ($type == 'int') {
			$value = (int)$value;
		} elseif ($type == 'float') {
			$value = (float)$value;
		} elseif ($type == 'bool') {
			$value = !empty($value);
		} else {
			$value = trim((string)$value);
		}
		$local[$local_field] = $value;
	}

	$errors = array();
	foreach ($required as $field) {
		$field = (string)$field;
		if (!array_key_exists($field, $local) || trim((string)$local[$field]) == '') {
			$errors[] = 'Missing required mapped field: ' . $field;
		}
	}

	$result['success'] = empty($errors);
	if (empty($errors)) {
		$result['message'] = 'API fields mapped to local record.';
	} else {
		$result['message'] = 'API field mapping failed validation.';
	}
	$result['data'] = array(
		'record' => $local,
		'errors' => $errors,
		'warnings' => $warnings
	);

	return $result;
}