Integer List Validator

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

/**
 * Parses lists of IDs and rejects invalid, duplicate, or out-of-range values.
 *
 * Primary use case: Bulk actions, category assignments, filters.
 * Typical inputs: raw list, min, max, max count.
 * Typical output: integer array or errors.
 *
 * Implementation note: Cast after validation; cap list size.
 *
 * @param mixed $values Array, CSV string, or scalar integer-like value.
 * @param int $minimum Minimum accepted integer value.
 * @param int $maximum Maximum accepted integer value. Use 0 for no maximum.
 * @param int $max_count Maximum accepted item count.
 * @return array Structured validation result with integers, rejected values, and duplicates.
 */
function ogValidateIntegerList($values, $minimum = 1, $maximum = 0, $max_count = 100) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$minimum = (int)$minimum;
	$maximum = (int)$maximum;
	$max_count = (int)$max_count;

	if ($max_count < 1) {
		$max_count = 1;
	}

	if (is_string($values)) {
		$values = explode(',', $values);
	} elseif (is_int($values) || is_float($values)) {
		$values = array($values);
	} elseif (!is_array($values)) {
		$result['message'] = 'Integer list must be an array, CSV string, or scalar integer.';
		return $result;
	}

	$integers = array();
	$rejected = array();
	$duplicates = array();
	$seen = array();

	foreach ($values as $value) {
		$value = trim((string)$value);
		if ($value === '') {
			continue;
		}

		if (!preg_match('/^-?[0-9]+$/', $value)) {
			$rejected[] = $value;
			continue;
		}

		$integer = (int)$value;
		if ($integer < $minimum) {
			$rejected[] = $value;
			continue;
		}
		if ($maximum > 0 && $integer > $maximum) {
			$rejected[] = $value;
			continue;
		}

		$key = (string)$integer;
		if (!empty($seen[$key])) {
			$duplicates[] = $integer;
			continue;
		}

		$seen[$key] = true;
		$integers[] = $integer;
	}

	if (count($integers) > $max_count) {
		$result['message'] = 'Integer list exceeds the allowed item count.';
		$result['data'] = array(
			'integers' => array_slice($integers, 0, $max_count),
			'rejected' => $rejected,
			'duplicates' => $duplicates,
			'truncated' => true
		);
		return $result;
	}

	$result['success'] = empty($rejected);
	if (empty($rejected)) {
		$result['message'] = 'Integer list validated.';
	} else {
		$result['message'] = 'Integer list contains rejected values.';
	}
	$result['data'] = array(
		'integers' => $integers,
		'rejected' => $rejected,
		'duplicates' => $duplicates,
		'truncated' => false
	);

	return $result;
}