[RateLimiter] Add `CalendarWindowLimiter` #62127

Crovitche-1623 · 2025-10-22T13:00:31Z

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues
License	MIT

I was looking to rate limit an API that I proxy to another. However, the pricing for the API I am calling is based on a calendar quota (we receive the bill at the end of the month).

On Symfony, I saw that there was a fixed_window policy, which corresponds to a counter for a given interval.

However, the counter seems to start when the request is made, not on a calendar basis.

I could reset the cache used by the rate_limiter at the beginning of the month to make sure it's correct, but that seemed a bit messy.

That's why I propose this CalendarWindowLimiter that can rate limit based on the given CalendarInterval enum value.

The usage would be something like that :

# config/packages/rate_limiter.yaml
framework:
    rate_limiter:
        a_gafam_api_that_gives_a_free_quota:
            policy: calendar_window

            limit: 10000

            calendar_interval: month

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindow.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindowType.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindowLimiter.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindow.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindowLimiter.php

src/Symfony/Component/RateLimiter/Policy/CalendarWindowType.php

src/Symfony/Component/RateLimiter/Tests/Policy/CalendarWindowTest.php

…move the default value

…ndowLimiter`

src/Symfony/Component/RateLimiter/Policy/CalendarWindowLimiter.php

src/Symfony/Component/RateLimiter/RateLimiterFactory.php

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php

src/Symfony/Component/RateLimiter/Policy/CalendarInterval.php

src/Symfony/Component/RateLimiter/RateLimiterFactory.php

…nt is not installed

Crovitche-1623 · 2025-10-24T08:05:20Z

@stof The CI seems to fail because the Psr\Clock\ClockInterface interface is not found in a test. The other limiters were not developed using PSR-20 ClockInterface but regular time() functions and mocked using the ClockMock offered by the PhpUnit Bridge.

What should I do in this case? Rewrite the code using regular time() functions or require the psr/clock at least in --dev for testing?

stof · 2025-10-24T08:48:21Z

you need to add a dev requirement for that optional dependency.

Crovitche-1623 · 2025-10-24T09:11:16Z

you need to add a dev requirement for that optional dependency.

Are we sure it's not just a regular dependency, since it's now used in CalendarWindowLimiter.php?

stof · 2025-10-24T09:50:31Z

the clock is optional in that limiter.

… should be optional

…8.3.

…owLimiter`

Crovitche-1623 · 2025-10-25T09:25:37Z

Everything seems fine on my end 😁. The tests that crashed in CI don't seem to be related to my code.

feat: add CalendarWindowLimiter

dec7fe2

carsonbot added Status: Needs Review Feature RateLimiter labels Oct 22, 2025

carsonbot added this to the 7.4 milestone Oct 22, 2025

Crovitche-1623 added 5 commits October 22, 2025 15:10

chore: cs

1a1523f

chore: cs

22f09ea

chore: compatibility with php < 8.4

edda9c1

chore: cs

0fe0409

fix: fix incorrect format for daily window type

433dbfd

stof reviewed Oct 22, 2025

View reviewed changes

Crovitche-1623 added 13 commits October 22, 2025 15:42

chore: remove declare(strict_types=1);

f9df2b4

chore: remove declare(strict_types=1);

3de65ed

chore: use test prefix instead of #[Test] attribute

eeeab00

chore: CalendarWindowType cannot be internal if it's used in config

9275edc

chore: more consistency with id

3990f9b

chore: symfony does not use #[\Override]

60fc9a5

chore: rename $clock to $timer like the others rate limiters + re…

788cefe

…move the default value

chore: use calendar_interval enum node instead of a free array.

f29045b

chore: use an enum instead of a string to instantiate the `CalendarWi…

50959d6

…ndowLimiter`

chore: remove unnecessary return types for test

2760252

chore: rename CalendarWindowType to CalendarInterval

d83555e

feat: use a PSR-20 clock instead, so we can mock the time later.

3dd4074

chore: cs --> ordered use

c4370b2

stof reviewed Oct 22, 2025

View reviewed changes

Crovitche-1623 added 5 commits October 22, 2025 20:56

refactor: set CalendarInterval enum as allowed type instead

9e105d4

refactor: hardcode values, so it'll work even if rate limiter compone…

bf4bb79

…nt is not installed

refactor: better names for CalendarInterval values

1244427

refactor: missing type cast + typo + inject clock

dfeb411

refactor: nullable Clock to avoid a hard dependency

d53d3ec

Crovitche-1623 added 9 commits October 23, 2025 09:06

refactor: inject clock service if available

e09efb4

refactor: try to fix static analysis (psalm)

14b5965

tests: add missing test

abf3c6b

refactor: typo hour instead of hourl

2ed15cc

refactor: typo hour instead of hourl

f4d85a8

feat: a window must be serializable to be stored

d8b19d1

tests: mock ClockInterface without having to install Clock component

a4f4e15

refactor: cs + exception messages should end with a dot

541a9c1

fix: incorrect unserialize + cs

ebbc964

Crovitche-1623 requested a review from stof October 24, 2025 08:05

tests: avoid #[Test] attribute

1aea879

build: add psr/clock because we need ClockInterface

3256901

Crovitche-1623 added 5 commits October 24, 2025 14:05

fix: reset method + added few tests

24bcfc0

build: moved the psr/clock to dev dependencies because ClockInterface…

e67c2f8

… should be optional

refactor: cs + readonly class

5959f7c

fix: anonymous readonly classes are only available starting with PHP …

7021eb2

…8.3.

refactor: simplify code and added test to cover 100% of `CalendarWind…

4ed6edd

…owLimiter`

nicolas-grekas modified the milestones: 7.4, 8.1 Nov 16, 2025

Uh oh!

[RateLimiter] Add CalendarWindowLimiter #62127

Are you sure you want to change the base?

[RateLimiter] Add CalendarWindowLimiter #62127

Uh oh!

Conversation

Crovitche-1623 commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Crovitche-1623 commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stof commented Oct 24, 2025

Uh oh!

Crovitche-1623 commented Oct 24, 2025

Uh oh!

stof commented Oct 24, 2025

Uh oh!

Crovitche-1623 commented Oct 25, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[RateLimiter] Add `CalendarWindowLimiter` #62127

[RateLimiter] Add `CalendarWindowLimiter` #62127

Crovitche-1623 commented Oct 22, 2025 •

edited

Loading

Crovitche-1623 commented Oct 24, 2025 •

edited

Loading