<?php
// SPDX-License-Identifier: GPL-3.0-or-later
declare(strict_types=1);

namespace Aiwend\Usage;

/**
 * The periods of the usage reports, taken from the site's own calendar. A day is whatever the time zone says it is (23, 24 or 25
 * hours) and a month is a calendar month, so a request is never assigned to the wrong day by assuming 86,400 seconds. Periods are
 * returned newest first, contiguous (each ends exactly where the next newer one starts) and bounded: at most 31 days and 12 months.
 */
final class UsageSeries
{
    public const MAX_DAYS = 31;
    public const MAX_MONTHS = 12;

    /** @return list<array{start:int, end:int}> */
    public static function days(int $now, \DateTimeZone $tz, int $count = self::MAX_DAYS): array
    {
        return self::periods($now, $tz, max(1, min(self::MAX_DAYS, $count)), 'today midnight', static fn(\DateTimeImmutable $d): \DateTimeImmutable => $d->modify('+1 day')->setTime(0, 0));
    }

    /** @return list<array{start:int, end:int}> */
    public static function months(int $now, \DateTimeZone $tz, int $count = self::MAX_MONTHS): array
    {
        return self::periods($now, $tz, max(1, min(self::MAX_MONTHS, $count)), 'first day of this month midnight', static fn(\DateTimeImmutable $d): \DateTimeImmutable => $d->modify('first day of next month')->setTime(0, 0));
    }

    /**
     * @param callable(\DateTimeImmutable): \DateTimeImmutable $next the start of the period that follows the one starting at the argument
     * @return list<array{start:int, end:int}>
     */
    private static function periods(int $now, \DateTimeZone $tz, int $count, string $anchor, callable $next): array
    {
        $start = (new \DateTimeImmutable('@' . $now))->setTimezone($tz)->modify($anchor);
        $end = $next($start);
        $out = [];
        for ($i = 0; $i < $count; $i++) {
            $out[] = ['start' => $start->getTimestamp(), 'end' => $end->getTimestamp()];
            $end = $start;
            // The instant one second before this period began lies in the previous period, and that period's start is its anchor.
            // Stepping back by an elapsed second (not by wall-clock arithmetic) is what survives days of 23 or 25 hours and midnights
            // that do not exist: a wall-clock step from 01:00 on a day without a midnight lands on the same day again.
            $start = (new \DateTimeImmutable('@' . ($start->getTimestamp() - 1)))->setTimezone($tz)->modify($anchor);
        }
        return $out;
    }
}