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

/**
 * Compares submitted form data to existing DB data and returns only changed fields.
 *
 * Primary use case: Admin edit screens and audit logs.
 * Typical inputs: old record, new record, tracked fields.
 * Typical output: change set array.
 *
 * Implementation note: Normalize values before comparing.
 *
 * @param array $old_record Existing stored record.
 * @param array $new_record Submitted or imported replacement record.
 * @param array $tracked_fields Optional allowlist of fields to compare.
 * @return array Structured change-set result.
 */
function ogBuildRecordChangeSet($old_record = array(), $new_record = array(), $tracked_fields = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($old_record) || !is_array($new_record)) {
		$result['message'] = 'Old and new records must be arrays.';
		return $result;
	}

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

	if (empty($tracked_fields)) {
		$tracked_fields = array_unique(array_merge(array_keys($old_record), array_keys($new_record)));
	}

	$changes = array();
	foreach ($tracked_fields as $field) {
		$field = (string)$field;
		$old_value = '';
		$new_value = '';
		if (array_key_exists($field, $old_record)) {
			$old_value = $old_record[$field];
		}
		if (array_key_exists($field, $new_record)) {
			$new_value = $new_record[$field];
		}
		if (is_scalar($old_value)) {
			$old_compare = trim((string)$old_value);
		} else {
			$old_compare = json_encode($old_value);
		}
		if (is_scalar($new_value)) {
			$new_compare = trim((string)$new_value);
		} else {
			$new_compare = json_encode($new_value);
		}
		if ($old_compare !== $new_compare) {
			$changes[$field] = array(
				'old' => $old_value,
				'new' => $new_value
			);
		}
	}

	$result['success'] = true;
	$result['message'] = 'Record change set built.';
	$result['data'] = array(
		'changed' => !empty($changes),
		'change_count' => count($changes),
		'changes' => $changes
	);

	return $result;
}