Record Validation Report 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.
 */

/**
 * Turns validation errors into grouped row/field reports suitable for admin display.
 *
 * Primary use case: CSV import previews and bulk updates.
 * Typical inputs: validation errors, row numbers.
 * Typical output: report array and HTML-ready data.
 *
 * Implementation note: Escape display separately from stored error codes.
 *
 * @param array $errors Validation errors from import or bulk processing.
 * @param array $options Optional severity labels and max display count.
 * @return array Structured validation report.
 */
function ogBuildRecordValidationReport($errors = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$max_display = 500;
	if (!empty($options['max_display'])) {
		$max_display = (int)$options['max_display'];
	}
	if ($max_display < 1) {
		$max_display = 1;
	}

	$rows = array();
	$field_counts = array();
	$total = 0;

	foreach ($errors as $error) {
		if (!is_array($error)) {
			continue;
		}
		$row_number = 0;
		if (!empty($error['row'])) {
			$row_number = (int)$error['row'];
		}
		$field = 'general';
		if (!empty($error['field'])) {
			$field = (string)$error['field'];
		}
		$message = 'Validation error.';
		if (!empty($error['message'])) {
			$message = (string)$error['message'];
		}
		if (empty($rows[$row_number])) {
			$rows[$row_number] = array();
		}
		if (count($rows[$row_number]) < $max_display) {
			$rows[$row_number][] = array(
				'field' => $field,
				'message' => $message,
				'display_message' => htmlspecialchars($message, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8')
			);
		}
		if (empty($field_counts[$field])) {
			$field_counts[$field] = 0;
		}
		$field_counts[$field]++;
		$total++;
	}

	$result['success'] = true;
	$result['message'] = 'Validation report built.';
	$result['data'] = array(
		'total_errors' => $total,
		'rows' => $rows,
		'field_counts' => $field_counts
	);

	return $result;
}