Cursor 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 a cursor-based API fetch plan.
 *
 * The helper caps limits and gives the caller explicit state to persist after
 * each API page is fetched.
 *
 * @param array $state Current cursor state.
 * @param array $options Pagination options.
 * @return array Cursor fetch plan.
 */
function ogBuildCursorFetchPlan($state = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

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

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

	$cursor = '';
	if (!empty($state['cursor'])) {
		$cursor = trim((string)$state['cursor']);
	}

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

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

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

	$complete = false;
	if (!empty($state['complete'])) {
		$complete = true;
	}
	if ($page_count >= $max_pages) {
		$complete = true;
	}

	$result['success'] = true;
	$result['message'] = 'Cursor fetch plan built.';
	$result['data'] = array(
		'should_fetch' => !$complete,
		'cursor' => $cursor,
		'limit' => $limit,
		'page_count' => $page_count,
		'max_pages' => $max_pages,
		'complete' => $complete,
		'next_state' => array(
			'cursor' => $cursor,
			'limit' => $limit,
			'page_count' => $page_count + 1
		)
	);

	return $result;
}