Pagination Request Cleaner

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

/**
 * Validates page number, page size, sort field, and sort direction.
 *
 * Primary use case: List pages and admin tables.
 * Typical inputs: GET params, allowed sort fields.
 * Typical output: pagination config array.
 *
 * Implementation note: Cap page size and allowlist sort columns.
 *
 * @param array $request Read-only request values, normally from a controlled GET intake.
 * @param array $allowed_sort_fields Approved database/display sort field names.
 * @param string $default_sort Default sort field.
 * @return array Structured pagination state.
 */
function ogCleanPaginationRequest($request = array(), $allowed_sort_fields = array(), $default_sort = 'id') {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

	$page = 1;
	if (!empty($request['page']) && preg_match('/^[0-9]+$/', (string)$request['page'])) {
		$page = (int)$request['page'];
	}
	if ($page < 1) {
		$page = 1;
	}

	$page_size = 25;
	if (!empty($request['page_size']) && preg_match('/^[0-9]+$/', (string)$request['page_size'])) {
		$page_size = (int)$request['page_size'];
	}
	if ($page_size < 1) {
		$page_size = 25;
	}
	if ($page_size > 100) {
		$page_size = 100;
	}

	$default_sort = trim((string)$default_sort);
	if (empty($default_sort)) {
		$default_sort = 'id';
	}
	if (empty($allowed_sort_fields)) {
		$allowed_sort_fields = array($default_sort);
	}

	$sort = $default_sort;
	if (!empty($request['sort'])) {
		$candidate_sort = trim((string)$request['sort']);
		if (in_array($candidate_sort, $allowed_sort_fields, true)) {
			$sort = $candidate_sort;
		}
	}

	$direction = 'ASC';
	if (!empty($request['direction'])) {
		$candidate_direction = strtoupper(trim((string)$request['direction']));
		if ($candidate_direction == 'DESC') {
			$direction = 'DESC';
		}
	}

	$offset = ($page - 1) * $page_size;

	$result['success'] = true;
	$result['message'] = 'Pagination request cleaned.';
	$result['data'] = array(
		'page' => $page,
		'page_size' => $page_size,
		'offset' => $offset,
		'sort' => $sort,
		'direction' => $direction
	);

	return $result;
}