phil / usage-meter-bundle
Quotas in Symfony: meters declared in configuration, counters in the database, limits from providers or subscriptions, rate limiters that count on a meter.
Package info
github.com/parler-haut-interagir-librement/usage-meter-bundle
Type:symfony-bundle
pkg:composer/phil/usage-meter-bundle
Requires
- php: >=8.5
- phil/rate-limit-bundle: ^0.1@dev
- phil/usage-meter: ^0.1@dev
- psr/clock: ^1.0
- symfony/config: ^8.2
- symfony/console: ^8.2
- symfony/dependency-injection: ^8.2
- symfony/http-foundation: ^8.2
- symfony/http-kernel: ^8.2
Requires (Dev)
- doctrine/dbal: ^4.5
- doctrine/doctrine-bundle: ^3.3
- doctrine/orm: ^3.7
- phil/commerce-subscription-bundle: ^0.1@dev
- phpunit/phpunit: ^13.4
- psr/log: ^3.0
- symfony/browser-kit: ^8.2
- symfony/clock: ^8.2
- symfony/event-dispatcher: ^8.2
- symfony/framework-bundle: ^8.2
- symfony/routing: ^8.2
- symfony/yaml: ^8.2
Suggests
- doctrine/dbal: For the store "dbal", the counters in a database
- doctrine/orm: To add the counter tables to the schema the ORM generates
- phil/commerce-subscription-bundle: For the limits read from the features of a subscriber's offers
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 03:05:46 UTC
README
Meters declared in configuration, counters kept in the database, and rate limiters that count on them.
phil/usage-meter-bundle brings phil/usage-meter into a Symfony application. The meters are declared in the
phil_usage_meter configuration — a limit and a period each: calendar days, weeks, months or years in a time zone,
billing periods from an anchor, or a rolling window in buckets — and checked when the container is built. The counters
live in two tables of a Doctrine DBAL connection, which join the schema the ORM generates so that a migration creates
them; the memory of one process, or a store of the application's, serve as well. The limit providers of the
application are asked in a chain, the features of a subscriber's offers last when phil/commerce-subscription-bundle
is installed, and an anchor provider gives each subject its own billing day.
It is for any Symfony application that holds its users to quotas: a free tier of three exports a month, an API that
allows so many calls an hour per address, a plan that caps the tokens of a billing period. Its rate limiters are
limiters of phil/rate-limit-bundle that count on a meter: #[RateLimit('api')], a route default or a form option
counts each request on the limiter's meter, for the request's key — the client's address or the signed-in user, kept as
keyed hashes, or the application's own —, so that a subscriber's limits and a calendar period apply to requests, and
phil/rate-limit-bundle answers 429 Too Many Requests with Retry-After and its rate-limit headers when the quota is
reached. bin/console phil:usage-meter:purge, run once a day, forgets the counters no window counts any more.
It is built on the components Symfony already ships: Config and DependencyInjection for the
configuration, HttpKernel for the refusal of a malformed Idempotency-Key, Console for the purge.
Status
| Part | State |
|---|---|
| Meters from configuration, each checked at build time: limit, calendar period, rolling window, billing cycle | Implemented and tested |
| Stores: DBAL with its tables in the ORM schema, in memory, or a service of the application | Implemented and tested |
| Limit providers in a chain, limits from subscription features, an anchor provider | Implemented and tested |
Rate limiters of phil/rate-limit-bundle on meters: keys by address, by user or by the application's resolver, the subject's limits |
Implemented and tested |
Retries counted once per Idempotency-Key header, opt-in per limiter, bound to the request by an HMAC |
Implemented and tested |
phil:usage-meter:purge |
Implemented and tested |
| Twig functions showing what a subject used and has left | Not started: templates read UsageMeter::usage() from the controller |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements, installing, the tables and the migration. |
| Configuration | Every key of phil_usage_meter: the store, the meters, the limits, the anchors. |
| Rate limiting | The limiters on meters, their keys, Idempotency-Key, the 429 answer and the headers. |
| Console | phil:usage-meter:purge and its schedule. |
| Extension points | The application's store, limit providers and anchor provider. |
| Exceptions | What the bundle throws, and when. |
| Testing | The bundle's tests, and how to test code that is metered or rate limited. |
| Reference | Every class, service and constant of the bundle. |
Quick start
composer require phil/usage-meter-bundle
# config/packages/phil_usage_meter.yaml phil_usage_meter: meters: exports: { limit: 3, calendar: month, timezone: America/Toronto } requests: { limit: 600, rolling: 3600, buckets: 60 } rate_limiters: api: { meter: requests, key: ip }
use Phil\UsageMeter\UsageMeter; use Phil\RateLimitBundle\Domain\Attribute\RateLimit; final class ExportController { #[RateLimit('api')] public function __invoke(UsageMeter $meter, string $accountId): Response { $meter->consume($accountId, 'exports'); // QuotaExceeded when the month's three are spent // ... } }
bin/console doctrine:migrations:diff # the two counter tables bin/console phil:usage-meter:purge # once a day
Requirements
PHP 8.5 or later, phil/usage-meter, phil/rate-limit-bundle, and the Symfony 8.2 components Config,
DependencyInjection, Console, HttpFoundation and HttpKernel. doctrine/dbal for the database store, doctrine/orm for its tables in the generated
schema, phil/commerce-subscription-bundle for limits from
subscription features — each only when used.
Contributing
Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.
License
MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.