Offset Pagination Fetcher

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 an offset/page based API fetch plan.
 *
 * Page size is capped so legacy APIs and exports cannot accidentally create
 * unbounded fetch loops.
 *
 * @param array $state Current page, offset, limit, and total state.
 * @param array $options Fetch policy options.
 * @return array Offset pagination plan.
 */
function ogBuildOffsetFetchPlan($state = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$page = 1;
	if (!empty($state['page'])) {
		$page = (int)$state['page'];
	}
	if ($page < 1) {
		$page = 1;
	}

	$limit = 100;
	if (!empty($state['limit'])) {
		$limit = (int)$state['limit'];
	}
	if ($limit < 1) {
		$limit = 1;
	}
	if ($limit > 500) {
		$limit = 500;
	}

	$total = 0;
	if (!empty($state['total'])) {
		$total = (int)$state['total'];
	}

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

	$offset = ($page - 1) * $limit;
	$total_pages = 0;
	if ($total > 0) {
		$total_pages = (int)ceil($total / $limit);
	}

	$should_fetch = true;
	if ($page > $max_pages) {
		$should_fetch = false;
	}
	if ($total_pages > 0 && $page > $total_pages) {
		$should_fetch = false;
	}

	$result['success'] = true;
	$result['message'] = 'Offset fetch plan built.';
	$result['data'] = array(
		'should_fetch' => $should_fetch,
		'page' => $page,
		'limit' => $limit,
		'offset' => $offset,
		'total' => $total,
		'total_pages' => $total_pages,
		'next_page' => $page + 1,
		'max_pages' => $max_pages
	);

	return $result;
}