Form Sticky Value 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.
 */

/**
 * Builds safe sticky form values after validation errors.
 *
 * This function does not perform final HTML escaping. It removes password-like
 * fields and normalizes scalar form values before the render layer escapes them.
 *
 * @param array $submitted Submitted form values.
 * @param array $defaults Default values used when a submitted value is missing.
 * @param array $field_policy Optional include/exclude and max length policy.
 * @return array Sticky form value map and excluded field list.
 */
function ogBuildStickyFormValues($submitted = array(), $defaults = array(), $field_policy = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

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

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

	$exclude_fields = array('password', 'password_confirm', 'current_password', 'new_password', 'csrf_token');
	if (!empty($field_policy['exclude_fields']) && is_array($field_policy['exclude_fields'])) {
		$exclude_fields = array_merge($exclude_fields, $field_policy['exclude_fields']);
	}

	$max_length = 500;
	if (!empty($field_policy['max_length'])) {
		$max_length = (int)$field_policy['max_length'];
	}
	if ($max_length < 20) {
		$max_length = 20;
	}

	$source = array_merge($defaults, $submitted);
	$values = array();
	$excluded = array();

	foreach ($source as $field => $value) {
		$field = (string)$field;
		if (empty($field)) {
			continue;
		}

		if (!empty($include_fields) && !in_array($field, $include_fields, true)) {
			$excluded[] = $field;
			continue;
		}

		if (in_array($field, $exclude_fields, true) || preg_match('/password|token|secret/i', $field)) {
			$excluded[] = $field;
			continue;
		}

		if (is_scalar($value)) {
			$value = trim((string)$value);
			$value = str_replace("\0", '', $value);
			if (strlen($value) > $max_length) {
				$value = substr($value, 0, $max_length);
			}
			$values[$field] = $value;
		} elseif (is_array($value)) {
			$clean_array = array();
			foreach ($value as $array_value) {
				if (is_scalar($array_value)) {
					$clean_array[] = trim((string)$array_value);
				}
			}
			$values[$field] = $clean_array;
		}
	}

	$result['success'] = true;
	$result['message'] = 'Sticky form values built.';
	$result['data'] = array(
		'values' => $values,
		'excluded_fields' => array_values(array_unique($excluded)),
		'escape_on_output' => true
	);

	return $result;
}