Download the PHP package monkeyscloud/monkeyslegion-rate-limit without Composer

MonkeysLegion Rate Limit

Production-grade rate limiting for MonkeysLegion Framework with token bucket and sliding window algorithms, Redis backend, and PSR-15 middleware.

Features

• Two algorithms: Token Bucket (burst-friendly) and Sliding Window (precise counting)
• Redis Lua scripts: Atomic operations — no race conditions at scale
• Composite key resolvers: Per-IP, per-user, per-route, or any combination (ip+route, user+route)
• #[RateLimit] attribute: Repeatable, class + method targets, named limiter references
• PSR-15 middleware: RFC-compliant rate limit headers
• Resilient storage: Fail-open/fail-closed modes with circuit breaker — no 500 errors when Redis is down
• MLC configuration: Full config file with env var overrides and named limiter definitions
• Telemetry integration: Optional metrics for monitoring (counters, gauges)
• GDPR compliance: Optional IP hashing, trusted proxy support
• PHP 8.4: Property hooks, backed enums, asymmetric visibility

Installation

For production use with Redis:

MLC Configuration

Copy the config file to your project's config/ directory:

Full Configuration Reference

Environment Variable Quick Reference

Bootstrapping with the Provider

Automatic (Recommended)

The RateLimitProvider wires everything from MLC config in a single call:

The Provider creates:

• $services['storage'] — The storage backend (Redis → ResilientStorage wrapper)
• $services['manager'] — RateLimiterManager with named limiters from config
• $services['middleware'] — RateLimitMiddleware ready for the router

DI Container Registration

With Pre-existing Redis Connection

If your app already has a shared Redis connection (e.g., from the queue or cache package):

Manual Bootstrap (Without Provider)

Quick Start — Using Rate Limits

Attribute-Based (Recommended)

Programmatic Usage (Facade)

From Attribute (Standalone)

Use fromAttribute() to evaluate rate limits from a #[RateLimit] attribute without the middleware:

Redis Unavailability — Resilient Storage

Neither Laravel nor Symfony handle this. Both throw 500 errors when Redis goes down. MonkeysLegion is the first PHP framework to ship a built-in resilient rate limiter.

The Problem

Three Modes of Operation

Circuit Breaker Pattern

Development Without Redis

Or in the MLC file:

Note: memory driver is single-process. Rate limits are not shared across workers.

Router Integration

The rate limiter hooks into the router via the #[RateLimit] attribute system:

How It Works

1. ControllerScanner scans for #[RateLimit] attributes on controller classes and methods
2. Rate limit configs are stored in meta['rate_limits'] on each RouteDefinition
3. Router::dispatch() attaches _rate_limits as a PSR-7 request attribute
4. RateLimitMiddleware reads _rate_limits, resolves keys, evaluates limits, returns 429 or adds headers

Backwards Compatibility

The existing #[Throttle] attribute continues to work — the scanner bridges it automatically:

Competitive Comparison

Algorithms

Token Bucket

Best for APIs that allow burst traffic while maintaining a steady average rate.

• Capacity = maxAttempts (burst size)
• Refill rate = maxAttempts / windowSeconds tokens per second
• Each request consumes cost tokens (default: 1)
• Tokens refill continuously based on elapsed time

Sliding Window

Best for strict rate limiting with precise request counting.

• Tracks each request timestamp in a rolling window
• No burst allowance — exactly maxAttempts per windowSeconds
• Uses Redis sorted sets for O(log n) operations

Key Resolvers

Response Headers

Follows RFC 6585 + draft-ietf-httpapi-ratelimit-headers.

On successful requests:

On rate-limited requests (429):

Telemetry Metrics

When telemetry is enabled, the middleware emits the following metrics via the callback:

Requirements

• PHP ^8.4
• ext-redis (recommended for production)
• PSR-7 HTTP Message ^2.0
• PSR-15 HTTP Server Middleware ^1.0

License

MIT License — see LICENSE for details.