Skip to content
Home
← Back to Functions
Code

Error List Grouper

Groups validation errors by field and general form level.

Function signature

ogGroupFormErrors(errors = array(), options = array())

Categories

  • Forms and Validation

Parameters

errorsValidation errors as strings or structured rows with field, code, and message keys.optionsOptional documented policy controls for this helper.

Return value

Public-safe status string returned by the function for explicit controller branching or logging.

  • success
  • message
  • data

Compatibility

Existing function name, slug, path, and call order preserved; advertised metadata corrected to the actual source behavior.

Minimum PHP version: 7.4

Security notes

Use caller-owned allowlists and context-specific escaping; validate admin actions, export fields, privacy plans, cache keys, templates, settings, routes, and ecommerce policies before production use.

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

/**
 * Groups validation errors by field and general form level.
 *
 * Primary use case: Form rendering.
 * Typical inputs: error array.
 * Typical output: grouped error list.
 *
 * Implementation note: Keep error codes separate from display text.
 *
 * @param array $errors Validation errors as strings or arrays with field, code, and message keys.
 * @param array $options Optional labels and public-message controls.
 * @return array Grouped form error data.
 */
function ogGroupFormErrors($errors = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$general_key = '_general';
	if (!empty($options['general_key'])) {
		$general_key = (string)$options['general_key'];
	}

	$grouped = array(
		'fields' => array(),
		'general' => array(),
		'codes' => array(),
		'count' => 0
	);

	foreach ($errors as $error) {
		$field = $general_key;
		$code = 'validation_error';
		$message = '';

		if (is_array($error)) {
			if (!empty($error['field'])) {
				$field = trim((string)$error['field']);
			}
			if (!empty($error['code'])) {
				$code = trim((string)$error['code']);
			}
			if (!empty($error['message'])) {
				$message = trim((string)$error['message']);
			}
		} else {
			$message = trim((string)$error);
		}

		if (empty($message)) {
			continue;
		}

		$error_row = array(
			'code' => $code,
			'message' => $message
		);

		if ($field == $general_key) {
			$grouped['general'][] = $error_row;
		} else {
			if (empty($grouped['fields'][$field])) {
				$grouped['fields'][$field] = array();
			}
			$grouped['fields'][$field][] = $error_row;
		}

		if (empty($grouped['codes'][$code])) {
			$grouped['codes'][$code] = 0;
		}
		$grouped['codes'][$code]++;
		$grouped['count']++;
	}

	$result['success'] = true;
	$result['message'] = 'Form errors grouped.';
	$result['data'] = $grouped;
	return $result;
}