API Throttle Window Tracker

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

/**
 * Tracks API quota windows and calculates whether another request may be sent.
 *
 * The helper returns an allow/delay decision from the current usage snapshot. It does not persist
 * state; callers should store returned usage data after sending a request.
 *
 * @param array $usage Current usage with used, limit, reset_at, and provider keys.
 * @param array $options Safety margin and default window policy.
 * @return array API throttle decision.
 */
function ogTrackApiThrottleWindow($usage = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($usage)) {
		$result['message'] = 'Usage data must be an array.';
		return $result;
	}
	if (!is_array($options)) {
		$options = array();
	}

	$used = 0;
	if (!empty($usage['used'])) {
		$used = (int)$usage['used'];
	}
	$limit = 60;
	if (!empty($usage['limit'])) {
		$limit = (int)$usage['limit'];
	}
	if ($limit < 1) {
		$limit = 1;
	}

	$reset_at = 0;
	if (!empty($usage['reset_at'])) {
		$reset_at = (int)$usage['reset_at'];
	}
	$window_seconds = 60;
	if (!empty($options['window_seconds'])) {
		$window_seconds = (int)$options['window_seconds'];
	}
	if ($window_seconds < 1) {
		$window_seconds = 60;
	}
	if ($reset_at <= time()) {
		$used = 0;
		$reset_at = time() + $window_seconds;
	}

	$safety_margin = 0;
	if (!empty($options['safety_margin'])) {
		$safety_margin = (int)$options['safety_margin'];
	}
	if ($safety_margin < 0) {
		$safety_margin = 0;
	}

	$remaining = $limit - $used;
	$allowed = true;
	$delay_seconds = 0;
	if ($remaining <= $safety_margin) {
		$allowed = false;
		$delay_seconds = $reset_at - time();
		if ($delay_seconds < 0) {
			$delay_seconds = 0;
		}
	}

	$result['success'] = true;
	$result['message'] = 'API throttle window evaluated.';
	$result['data'] = array(
		'allowed' => $allowed,
		'used' => $used,
		'limit' => $limit,
		'remaining' => $remaining,
		'reset_at' => $reset_at,
		'delay_seconds' => $delay_seconds
	);

	return $result;
}