symfony · Crovitche-1623 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php b/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php
@@ -2581,7 +2581,7 @@ private function addRateLimiterSection(ArrayNodeDefinition $rootNode, callable $
                                     ->enumNode('policy')
                                         ->info('The algorithm to be used by this limiter.')
                                         ->isRequired()
-                                        ->values(['fixed_window', 'token_bucket', 'sliding_window', 'compound', 'no_limit'])
+                                        ->values(['fixed_window', 'token_bucket', 'sliding_window', 'compound', 'no_limit', 'calendar_window'])
                                     ->end()
                                     ->arrayNode('limiters', 'limiter')
                                         ->info('The limiter names to use when using the "compound" policy.')
@@ -2603,6 +2603,10 @@ private function addRateLimiterSection(ArrayNodeDefinition $rootNode, callable $
                                             ->integerNode('amount')->info('Amount of tokens to add each interval.')->defaultValue(1)->end()
                                         ->end()
                                     ->end()
+                                    ->enumNode('calendar_interval')
+                                        ->info('Configures the chosen calendar interval if "policy" is set to "calendar_window".')
+                                        ->values(['year', 'month', 'day', 'hour', 'minute'])
+                                    ->end()
                                 ->end()
                                 ->validate()
                                     ->ifTrue(static fn ($v) => !\in_array($v['policy'], ['no_limit', 'compound'], true) && !isset($v['limit']))

diff --git a/src/Symfony/Bundle/FrameworkBundle/Resources/config/rate_limiter.php b/src/Symfony/Bundle/FrameworkBundle/Resources/config/rate_limiter.php
@@ -25,6 +25,7 @@
                 abstract_arg('config'),
                 abstract_arg('storage'),
                 null,
+                service('clock')->ignoreOnInvalid(),
             ])
     ;
 };
diff --git a/src/Symfony/Component/RateLimiter/CHANGELOG.md b/src/Symfony/Component/RateLimiter/CHANGELOG.md
@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Add `CalendarWindowLimiter`
+
 7.3
 ---
 

diff --git a/src/Symfony/Component/RateLimiter/Policy/CalendarInterval.php b/src/Symfony/Component/RateLimiter/Policy/CalendarInterval.php
@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\RateLimiter\Policy;
+
+/**
+ * @author Thibault Gattolliat <contact@thibaultg.info>
+ */
+enum CalendarInterval: string
+{
+    case YEAR = 'year';
+
+    case MONTH = 'month';
+
+    case DAY = 'day';
+
+    case HOUR = 'hour';
+
+    case MINUTE = 'minute';
+}
diff --git a/src/Symfony/Component/RateLimiter/Policy/CalendarWindow.php b/src/Symfony/Component/RateLimiter/Policy/CalendarWindow.php
@@ -0,0 +1,129 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\RateLimiter\Policy;
+
+use Symfony\Component\RateLimiter\LimiterStateInterface;
+
+/**
+ * @author Thibault Gattolliat <contact@thibaultg.info>
+ *
+ * @internal
+ */
+final class CalendarWindow implements LimiterStateInterface
+{
+    /**
+     * @var non-negative-int
+     */
+    private int $hitCount = 0;
+
+    /**
+     * @param positive-int $size
+     */
+    public function __construct(
+        private string $id,
+        private readonly CalendarInterval $calendarInterval,
+        private readonly int $size,
+        private readonly \DateTimeImmutable $timer,
+    ) {
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    private function intervalToFormat(): string
+    {
+        return match ($this->calendarInterval) {
+            CalendarInterval::YEAR => 'Y',
+            CalendarInterval::MONTH => 'Y-m',
+            CalendarInterval::DAY => 'Y-m-d',
+            CalendarInterval::HOUR => 'Y-m-d\\TH',
+            CalendarInterval::MINUTE => 'Y-m-d\\TH-i',
+        };
+    }
+
+    /**
+     * @param positive-int $tokens
+     */
+    public function add(int $tokens = 1): void
+    {
+        $this->hitCount += $tokens;
+    }
+
+    public function getAvailableTokens(): int
+    {
+        return $this->size - $this->hitCount;
+    }
+
+    public function calculateWaitTimeForTokens(int $tokens, \DateTimeInterface $now): int
+    {
+        if ($this->getAvailableTokens() >= $tokens) {
+            return 0;
+        }
+
+        return $this->getExpirationTime() - $now->getTimestamp();
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function getId(): string
+    {
+        return \sprintf('%s_%s', $this->id, $this->timer->format($this->intervalToFormat()));
+    }
+
+    /**
+     * @return non-negative-int
+     */
+    public function getExpirationTime(): int
+    {
+        $expirationTime = match ($this->calendarInterval) {
+            CalendarInterval::YEAR => $this->timer->modify('last day of December this year 23:59:59.999999'),
+            CalendarInterval::MONTH => $this->timer->modify('last day of this month 23:59:59.999999'),
+            CalendarInterval::DAY => $this->timer->setTime(23, 59, 59, 999999),
+            CalendarInterval::HOUR => $this->timer->setTime(
+                (int) $this->timer->format('H'),
+                59,
+                59,
+                999999,
+            ),
+            CalendarInterval::MINUTE => $this->timer->setTime(
+                (int) $this->timer->format('H'),
+                (int) $this->timer->format('i'),
+                59,
+                999999,
+            ),
+        };
+
+        return $expirationTime->getTimestamp();
+    }
+
+    /**
+     * @return array<non-empty-string, positive-int>
+     */
+    public function serialize(): array
+    {
+        if (0 === $this->hitCount) {
+            throw new \LogicException('A window with 0 hits should not be serialized.');
+        }
+
+        return [$this->getId() => $this->hitCount];
+    }
+
+    /**
+     * @param array<non-empty-string, positive-int> $data
+     */
+    public function unserialize(array $data): void
+    {
+        $this->id = array_key_first($data);
+        $this->hitCount = $data[$this->id];
+    }
+}
diff --git a/src/Symfony/Component/RateLimiter/Policy/CalendarWindowLimiter.php b/src/Symfony/Component/RateLimiter/Policy/CalendarWindowLimiter.php
@@ -0,0 +1,155 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\RateLimiter\Policy;
+
+use Psr\Clock\ClockInterface;
+use Symfony\Component\Lock\LockInterface;
+use Symfony\Component\RateLimiter\Exception\MaxWaitDurationExceededException;
+use Symfony\Component\RateLimiter\LimiterInterface;
+use Symfony\Component\RateLimiter\RateLimit;
+use Symfony\Component\RateLimiter\Reservation;
+use Symfony\Component\RateLimiter\Storage\StorageInterface;
+
+/**
+ * Limit the number of call on a calendar basis. This could be useful
+ * for instance if the numbers of call of a remote API is restricted on a
+ * monthly basis.
+ *
+ * Limitations: it'll work only with the gregorian calendar as PHP use it for
+ *              its DateTime objects.
+ *
+ * @author Thibault Gattolliat <contact@thibaultg.info>
+ */
+final readonly class CalendarWindowLimiter implements LimiterInterface
+{
+    private int $limit;
+
+    private \DateTimeImmutable $now;
+
+    public function __construct(
+        private string $id,
+        int $limit,
+        private CalendarInterval $calendarInterval,
+        private StorageInterface $storage,
+        private ?LockInterface $lock = null,
+        private ?ClockInterface $clock = null,
+    ) {
+        if ($limit < 1) {
+            throw new \InvalidArgumentException(\sprintf('Cannot set the limit of "%s" lower than 1, as that would never accept any hit.', __CLASS__));
+        }
+
+        $this->limit = $limit;
+        $this->now = $this->clock?->now() ?? new \DateTimeImmutable();
+    }
+
+    public function reset(): void
+    {
+        try {
+            $this->lock?->acquire(true);
+
+            $id = $this->getWindowId($this->now);
+
+            $this->storage->delete($id);
+        } finally {
+            $this->lock?->release();
+        }
+    }
+
+    public function reserve(
+        int $tokens = 1,
+        ?float $maxTime = null,
+    ): Reservation {
+        if ($tokens > $this->limit) {
+            throw new \InvalidArgumentException(\sprintf('Cannot reserve more tokens (%d) than the size of the rate limiter (%d).', $tokens, $this->limit));
+        }
+
+        $this->lock?->acquire(true);
+
+        try {
+            $window = $this->getOrCreateWindow($this->now);
+
+            $availableTokens = $window->getAvailableTokens();
+
+            if (0 === $tokens) {
+                // Note: the wait duration can be zero.
+                $waitDuration = $window->calculateWaitTimeForTokens($tokens, $this->now);
+
+                $reservationWillStartAt = $this->now->add(new \DateInterval('PT'.$waitDuration.'S'));
+
+                return new Reservation($reservationWillStartAt->getTimestamp(), new RateLimit($availableTokens, $reservationWillStartAt, true, $this->limit));
+            }
+
+            if ($availableTokens >= $tokens) {
+                $window->add($tokens);
+
+                $reservation = new Reservation($this->now->getTimestamp(), new RateLimit($window->getAvailableTokens(), $this->now, true, $this->limit));
+
+                $this->storage->save($window);
+
+                return $reservation;
+            }
+
+            $waitDuration = $window->calculateWaitTimeForTokens($tokens, $this->now);
+
+            $reservationWillStartAt = $this->now->add(new \DateInterval('PT'.$waitDuration.'S'));
+
+            if (null !== $maxTime && $waitDuration > $maxTime) {
+                throw new MaxWaitDurationExceededException(\sprintf('The rate limiter wait time ("%d" seconds) is longer than the provided maximum time ("%d" seconds).', $waitDuration, $maxTime), new RateLimit($availableTokens, $reservationWillStartAt, false, $this->limit));
+            }
+
+            $window->add($tokens);
+
+            $reservation = new Reservation($reservationWillStartAt->getTimestamp(), new RateLimit($availableTokens, $reservationWillStartAt, false, $this->limit));
+
+            $this->storage->save($window);
+
+            return $reservation;
+        } finally {
+            $this->lock?->release();
+        }
+    }
+
+    public function consume(int $tokens = 1): RateLimit
+    {
+        try {
+            return $this->reserve($tokens, 0)->getRateLimit();
+        } catch (MaxWaitDurationExceededException $e) {
+            return $e->getRateLimit();
+        }
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    private function getWindowId(\DateTimeImmutable $timer): string
+    {
+        return (new CalendarWindow($this->id, $this->calendarInterval, $this->limit, $timer))->getId();
+    }
+
+    private function getOrCreateWindow(\DateTimeImmutable $timer): CalendarWindow
+    {
+        $windowId = $this->getWindowId($timer);
+
+        /**
+         * @var CalendarWindow|null $window
+         */
+        $window = $this->storage->fetch($windowId);
+
+        if (null === $window) {
+            $window = new CalendarWindow($this->id, $this->calendarInterval, $this->limit, $timer);
+
+            $this->storage->save($window);
+        }
+
+        return $window;
+    }
+}