Record Field Transformer

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

/**
 * Applies explicit field transformation rules to one record.
 *
 * Supported rules include trim, lower, upper, int, decimal, bool, date,
 * null_empty, and max_length. Unknown rules are reported as warnings.
 *
 * @param array $record Source record.
 * @param array $rules Field rules by field name.
 * @return array Structured result with transformed record and warnings.
 */
function ogTransformRecordFields($record, $rules = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$transformed = $record;
	$warnings = array();

	foreach ($rules as $field => $field_rules) {
		$field = (string)$field;
		if (!array_key_exists($field, $transformed)) {
			$warnings[] = 'Missing field: ' . $field;
			continue;
		}

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

		$value = $transformed[$field];
		foreach ($field_rules as $rule_key => $rule_value) {
			$rule = $rule_value;
			if (!is_numeric($rule_key)) {
				$rule = $rule_key;
			}
			$rule = (string)$rule;

			if ($rule == 'trim') {
				$value = trim((string)$value);
			} elseif ($rule == 'lower') {
				$value = strtolower((string)$value);
			} elseif ($rule == 'upper') {
				$value = strtoupper((string)$value);
			} elseif ($rule == 'int') {
				$value = (int)$value;
			} elseif ($rule == 'decimal') {
				$value = (float)preg_replace('/[^0-9.-]/', '', (string)$value);
			} elseif ($rule == 'bool') {
				if (preg_match('/^(1|yes|true|on)$/i', trim((string)$value))) {
					$value = 1;
				} else {
					$value = 0;
				}
			} elseif ($rule == 'date') {
				$time = strtotime((string)$value);
				if ($time === false) {
					$value = '';
				} else {
					$value = date('Y-m-d', $time);
				}
			} elseif ($rule == 'null_empty') {
				if (trim((string)$value) === '') {
					$value = null;
				}
			} elseif ($rule == 'max_length') {
				$max_length = (int)$rule_value;
				if ($max_length > 0 && strlen((string)$value) > $max_length) {
					$value = substr((string)$value, 0, $max_length);
				}
			} else {
				$warnings[] = 'Unknown transform rule: ' . $rule;
			}
		}

		$transformed[$field] = $value;
	}

	$result['success'] = true;
	$result['message'] = 'Record fields transformed.';
	$result['data'] = array(
		'record' => $transformed,
		'warnings' => $warnings
	);

	return $result;
}