Helpers.php

<?php declare(strict_types=1);

/**
 * This file is part of the Nette Framework (https://nette.org)
 * Copyright (c) 2004 David Grudl (https://davidgrudl.com)
 */

namespace Nette\Http;

use Nette;
use Nette\Utils\DateTime;
use function array_shift, arsort, explode, is_int, preg_match, strtolower, trim;


/**
 * Helper functions for HTTP requests, responses and headers.
 */
final class Helpers
{
	use Nette\StaticClass;


	/**
	 * Formats a date and time in the HTTP date format (RFC 7231), e.g. 'Mon, 23 Jan 1978 10:00:00 GMT'.
	 */
	public static function formatDate(string|int|\DateTimeInterface $time): string
	{
		$time = DateTime::from($time)->setTimezone(new \DateTimeZone('GMT'));
		return $time->format('D, d M Y H:i:s \G\M\T');
	}


	/**
	 * Converts an expiration value to the number of seconds from now (may be negative for the past).
	 * An integer or a string representing an integer is taken directly as the number of seconds; a
	 * DateTimeInterface or any other textual string (e.g. '20 minutes', '2024-01-01') is treated as an
	 * absolute time. Returns null for null (no value); an empty string is rejected as it is never meaningful.
	 * A number that looks like an absolute UNIX timestamp is deprecated (pass a DateTimeInterface instead).
	 * @throws Nette\InvalidArgumentException  for an empty string
	 * @throws \Exception  for an unparsable textual time
	 */
	public static function expirationToSeconds(string|int|\DateTimeInterface|null $expire): ?int
	{
		return match (true) {
			$expire === null => null,
			is_int($expire) => self::secondsFromNumber($expire),
			$expire instanceof \DateTimeInterface => $expire->getTimestamp() - time(),
			$expire === '' => throw new Nette\InvalidArgumentException('Expiration must not be an empty string; use null instead.'),
			($seconds = filter_var($expire, FILTER_VALIDATE_INT)) !== false => self::secondsFromNumber($seconds),
			default => (new DateTime($expire))->getTimestamp() - time(),
		};
	}


	/** Treats a number as a relative interval, but tolerates an absolute UNIX timestamp for BC (deprecated). */
	private static function secondsFromNumber(int $seconds): int
	{
		if ($seconds >= 1_000_000_000) { // ~ year 2001; no sane relative interval is this large, so it is almost certainly an absolute timestamp
			trigger_error('Passing an absolute timestamp as an expiration is deprecated; pass a relative number of seconds or a DateTimeInterface instead.', E_USER_DEPRECATED);
			return $seconds - time();
		}

		return $seconds;
	}


	/**
	 * Parses an HTTP quality-value list such as the Accept, Accept-Language or Accept-Encoding header
	 * into tokens mapped to their q-factor, ordered by descending preference. Tokens are lowercased and
	 * those explicitly rejected with q=0 are omitted.
	 * @return array<string, float>  e.g. ['cs-cz' => 1.0, 'en' => 0.8]
	 */
	public static function parseQualityList(string $header): array
	{
		$list = [];
		foreach (explode(',', $header) as $item) {
			$params = explode(';', $item);
			$token = strtolower(trim((string) array_shift($params)));
			if ($token === '') {
				continue;
			}

			$q = 1.0;
			foreach ($params as $param) {
				if (preg_match('#^\s*q\s*=\s*([0-9.]+)#i', $param, $m)) {
					$q = min(1.0, (float) $m[1]); // q is capped at 1 per RFC 9110
				}
			}

			if ($q > 0) {
				$list[$token] = max($list[$token] ?? 0.0, $q); // a repeated token keeps its highest q
			}
		}

		arsort($list); // stable since PHP 8.0, so equal q keeps header order
		return $list;
	}


	/**
	 * Checks whether an IP address falls within a CIDR block (e.g. '192.168.1.0/24').
	 */
	public static function ipMatch(string $ip, string $mask): bool
	{
		return IPAddress::tryFrom($ip)?->isInRange($mask) ?? false;
	}
}