Null Empty Normalizer

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

/**
 * Converts configured empty-like values into nulls or defaults consistently.
 *
 * Primary use case: Imports, APIs, database writes.
 * Typical inputs: record, empty markers, default policy.
 * Typical output: normalized record.
 *
 * Implementation note: Do not convert legitimate zero values to null.
 *
 * @param array $record Record to normalize.
 * @param array $options Optional empty_values, defaults, and null_fields arrays.
 * @return array Structured normalized record result.
 */
function ogNormalizeEmptyValues($record = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$empty_values = array('', 'n/a', 'na', 'null', 'none', '-');
	if (!empty($options['empty_values']) && is_array($options['empty_values'])) {
		$empty_values = $options['empty_values'];
	}

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

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

	$normalized = array();
	$changed = array();

	foreach ($record as $field => $value) {
		$field = (string)$field;
		$new_value = $value;
		if (is_string($value)) {
			$trimmed = trim($value);
			$compare = strtolower($trimmed);
			if (in_array($compare, $empty_values, true)) {
				if (array_key_exists($field, $defaults)) {
					$new_value = $defaults[$field];
				} elseif (in_array($field, $null_fields, true)) {
					$new_value = null;
				} else {
					$new_value = '';
				}
				$changed[] = $field;
			} else {
				$new_value = $trimmed;
			}
		}
		$normalized[$field] = $new_value;
	}

	$result['success'] = true;
	$result['message'] = 'Empty values normalized.';
	$result['data'] = array(
		'record' => $normalized,
		'changed_fields' => $changed,
		'changed_count' => count($changed)
	);

	return $result;
}