Safe Merge Records

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

/**
 * Merges two records with explicit priority and conflict reporting.
 *
 * Policy options: priority = primary|secondary|filled, protected_fields = array().
 * Protected fields are never overwritten by secondary values.
 *
 * @param array $primary_record Base record.
 * @param array $secondary_record Incoming record.
 * @param array $policy Merge policy.
 * @return array Structured result with merged record and conflicts.
 */
function ogMergeRecordData($primary_record, $secondary_record, $policy = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	if (!is_array($policy)) {
		$policy = array();
	}

	$priority = 'primary';
	if (!empty($policy['priority'])) {
		$priority = (string)$policy['priority'];
	}

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

	$merged = $primary_record;
	$conflicts = array();

	foreach ($secondary_record as $field => $secondary_value) {
		$field = (string)$field;
		if (in_array($field, $protected_fields, true)) {
			continue;
		}

		if (!array_key_exists($field, $merged)) {
			$merged[$field] = $secondary_value;
			continue;
		}

		$primary_value = $merged[$field];
		if ((string)$primary_value !== (string)$secondary_value) {
			$conflicts[$field] = array(
				'primary' => $primary_value,
				'secondary' => $secondary_value
			);
		}

		if ($priority == 'secondary') {
			$merged[$field] = $secondary_value;
		} elseif ($priority == 'filled') {
			if (trim((string)$primary_value) === '' && trim((string)$secondary_value) !== '') {
				$merged[$field] = $secondary_value;
			}
		}
	}

	$result['success'] = true;
	$result['message'] = 'Records merged.';
	$result['data'] = array(
		'record' => $merged,
		'conflicts' => $conflicts,
		'protected_fields' => $protected_fields
	);

	return $result;
}