Download the PHP package colinmollenhour/rate-limiter without Composer

Cm\RateLimiter is a flexible PHP library implementing multiple rate limiting algorithms using Redis with enhanced API supporting separate burst capacity and sustained rates plus concurrency-aware rate limiting to prevent request pileup. Includes comprehensive performance testing and supports Redis alternatives like Dragonfly, KeyDB, and Valkey.

Note: This is a standalone fork of bvtterfly/sliding-window-rate-limiter, refactored to remove Laravel dependencies and support multiple algorithms.

Features

• Multiple Rate Limiting Algorithms - Sliding Window, Fixed Window, Leaky Bucket, GCRA, Token Bucket, and Concurrency-Aware
• Concurrency-Aware Limiting - Prevents request pileup from slow operations by limiting both rate AND concurrency
• Burst Allowances - Separate burst capacity and sustained rate parameters for fine-grained control
• Automatic Key Expiration - Redis keys automatically expire to prevent memory leaks with random keys
• High Performance - They are all fast, but GCRA algorithm achieves ~25,900 RPS with sub-millisecond latency
• Atomic Operations - All algorithms use Lua scripts for consistency and thread safety
• Redis Compatible - Works with Redis, Dragonfly, KeyDB, Valkey, AWS ElastiCache
• Laravel-Free - Standalone library with minimal dependencies (PHP 8.0+, Credis)
• Comprehensive Unit Testing - Full PHPUnit test suite
• Rigorous Stress Testing - Includes a stress-test suite for benchmarking all algorithms under load
• Interactive Playground - Web interface for testing algorithms with real-time results

Installation

See Packagist for the latest version.

Quick Start

1. Install the library and set up a Redis client (using Credis).
2. Create a RateLimiterFactory with the Redis client.
3. Choose a rate limiting algorithm with or without concurrency control and create a rate limiter instance.
4. Use the attempt() or attemptWithConcurrency() method to check if a request is allowed based on your rate limits.

Example without Concurrency Control

Example with Concurrency Control

🚀 Concurrency-Aware Rate Limiting

Solves the "request pileup" problem: Even with rate limiting, slow operations can pile up and overwhelm backends.

Example Problem:

• Rate limit: 10 requests/second ✅
• Request duration: 5 seconds ⚠️
• Result: ~40 concurrent requests piling up! ❌

Composable API Design

Any rate limiting algorithm can be combined with concurrency control using the factory:

How It Works

1. Concurrency Check First - Acquire a concurrency slot using Redis semaphore pattern
2. Rate Limit Check Second - Only requests with concurrency slots count against rate limits
3. Clear Failure Modes - Different response codes for concurrency (503) vs rate limiting (429)
4. Composable Design - Any algorithm can be combined with concurrency control

Use Cases

Algorithms

Each algorithm uses atomic Redis operations via Lua scripts for consistency and performance.

Sliding Window

• How it works: Tracks individual request timestamps using Redis sorted sets, smooths traffic over time
• Burst behavior: Ignores burst capacity parameter, provides smooth rate limiting based on sustained rate
• Pros: Precise rate limiting, smooth traffic distribution
• Cons: Higher memory usage, no true burst support
• Use when: You need accurate, smooth rate limiting

Fixed Window

• How it works: Simple counter per time window, resets at interval boundaries
• Burst behavior: Uses burst capacity as the window limit, ignores sustained rate parameter
• Pros: Memory efficient, high performance, allows full burst at window start
• Cons: Can allow up to 2x burst at window boundaries (e.g., 100 requests at 11:59 + 100 at 12:01)
• Use when: High traffic where burst at window boundaries is acceptable

Leaky Bucket

• How it works: Simulates a bucket that leaks at a constant rate, requests fill the bucket
• Burst behavior: Uses burst capacity as bucket size, ignores sustained rate (leak rate fixed at capacity/window)
• Pros: Allows initial burst up to capacity, enforces steady leak rate, accommodates traffic spikes
• Cons: More complex than fixed window, moderate memory usage
• Use when: Need burst tolerance while maintaining steady average rate

GCRA (Generic Cell Rate Algorithm)

• How it works: Uses theoretical arrival time (TAT) to lazily compute when next request can be made
• Burst behavior: Ignores burst capacity, provides smooth rate limiting based on sustained rate
• Pros: Very memory efficient (single value per key), smooth rate limiting, precise control, highest performance
• Cons: More complex algorithm, no true burst support
• Use when: Need memory-efficient rate limiting with smooth, predictable behavior, or maximum performance

Token Bucket

• How it works: A bucket holds tokens that are consumed by requests and refilled at a constant rate
• Burst behavior: Perfect implementation - supports both burst capacity (initial tokens) and sustained rate (refill rate)
• Pros: True burst + sustained rate support, allows bursts up to capacity, intuitive model, gradual refill prevents starvation
• Cons: More memory usage than GCRA, moderate complexity
• Use when: Need true burst tolerance with separate sustained rate control, web APIs with bursty traffic patterns

Choosing the Right Algorithm

Need True Burst + Sustained Rate Control?

→ Use Token Bucket - The only algorithm that properly implements both parameters.

Need Maximum Performance?

→ Use GCRA - Highest throughput (~2x faster) with lowest memory usage.

Need Smooth Rate Limiting?

→ Use Sliding Window or GCRA - Both provide smooth traffic distribution without burst spikes.

Need Simple High-Performance Solution?

→ Use Fixed Window - Lowest complexity, highest throughput after GCRA, acceptable burst behavior.

Need Burst with Average Rate Control?

→ Use Leaky Bucket - Good balance of burst tolerance and average rate enforcement.

Performance Comparison

Based on max-speed benchmarking (requests/second with no throttling):

Key Insight: GCRA offers the lowest memory usage, highest performance, AND lowest latency (~3x faster than other algorithms), making it ideal for high-scale applications.

Advanced Usage

Enhanced API with Burst + Sustained Rate Support

This library provides a powerful API that separates burst capacity from sustained rate, giving you fine-grained control over rate limiting behavior.

Core Methods

API Parameters

• $key: Unique identifier for the rate limit (e.g., 'user:123', 'api:endpoint')
• $burstCapacity: Maximum requests allowed immediately (burst)
• $sustainedRate: Requests per second for sustained traffic (float)
• $window: Time window in seconds (default: 60)

Algorithm-Specific Behavior

Token Bucket (Perfect Burst + Sustained)

Fixed Window (Burst as Window Limit)

Sliding Window & GCRA (Smooth Rate)

Leaky Bucket (Burst as Capacity)

Factory Methods

Direct Instantiation

Result Objects

Standard Rate Limiting Result

Concurrency-Aware Result

Common Use Cases

Web API with Burst Tolerance

Concurrency-Aware API with Token Bucket

Pure Concurrency Control (No Rate Limiting)

Smooth Rate Limiting

High-Performance with Acceptable Bursts

Memory-Efficient Smooth Limiting

Unit Testing

This library includes a comprehensive PHPUnit test suite covering all algorithms and features.

Requires Redis running on localhost:6379.

Testing with Docker

🎮 Interactive Playground

The playground provides a web interface for testing rate limiting algorithms with real-time results:

Quick Examples

Key Parameters

• algorithm - Rate limiting algorithm (sliding, fixed, leaky, gcra, token)
• concurrent - Max concurrent requests (0=disabled, default=5)
• sleep - Simulate slow requests (seconds)
• burst/rate/window - Rate limiting parameters
• format - Response format (html or json)

Accessing the Playground

Docker (Recommended):

The Docker setup includes:

• FrankenPHP server running the playground on port 8080
• Redis server for rate limiting storage
• Auto-reload during development (volume mounted)

PHP Built-in Server:

Stress Testing

Comprehensive stress testing tools are included to benchmark and compare algorithms under load.

Test Files

• stress-test.php - Full comprehensive stress test with CLI options

Prerequisites

1. PHP Extensions Required:

   • pcntl - For multi-process testing
   • redis or Credis library - For Redis connectivity
2. Redis Server:
   • Must be running on localhost:6379
   • Will be cleared (FLUSHDB) during tests

Running Stress Tests

Basic functionality validation:

Full stress test with CLI options:

HTTP Load Testing with "hey" CLI

For real-world HTTP load testing against the playground, use the hey CLI tool.

Basic Load Testing:

Advanced Load Testing Scenarios:

Key "hey" Parameters:

• -n - Total number of requests
• -c - Number of concurrent workers
• -q - Rate limit (requests per second per worker)
• -t - Timeout for each request (seconds)
• -d - Duration of test (alternative to -n)

Expected Results:

• 200 OK - Request allowed by both rate and concurrency limits
• 429 Too Many Requests - Rate limit exceeded (Retry-After header included)
• 503 Service Unavailable - Concurrency limit exceeded (try again shortly)

Monitoring During Tests:

Test Scenarios

1. High Contention (--scenarios=high) - 5 keys, tests algorithm behavior under high contention
2. Medium Contention (--scenarios=medium) - 50 keys, balanced load testing
3. Low Contention (--scenarios=low) - 1000 keys, tests distributed load performance
4. Single Key Burst (--scenarios=burst) - 1 key, extreme contention scenario
5. Custom (--keys=N) - User-defined parameters

CLI Options

• --algorithms=sliding,fixed,leaky,gcra,token - Choose which algorithms to test
• --scenarios=high,medium,low,burst,all,custom - Select test scenarios
• --duration=SECONDS - Test duration (default: 30s)
• --processes=NUM - Concurrent processes (default: 20)
• --keys=NUM - Custom key count for custom scenarios
• --limiter-rps=NUM - Rate limiter sustained rate (requests/sec)
• --limiter-burst=NUM - Rate limiter burst capacity
• --limiter-window=SECONDS - Time window size (default: 60s)
• --concurrency-max=NUM - Maximum concurrent requests (enables concurrency mode for all algorithms)
• --concurrency-timeout=SECONDS - Timeout for concurrency requests (default: 30s)
• --verbose - Detailed output
• --no-clear - Keep Redis data between tests
• --max-speed - Performance mode: send requests as fast as possible (no throttling)
• --latency-precision=N - Number of decimal places for latency rounding (default: 2)
• --latency-sample=N - Sample rate for latency collection - collect every Nth measurement (default: 1 = all measurements)

Metrics Collected

For each algorithm and scenario:

• Total Requests - Total attempts made
• Requests/sec (RPS) - Throughput achieved
• Success Rate % - Requests allowed through
• Block Rate % - Total requests blocked (rate + concurrency)
• Concurrency Block % - Requests blocked by concurrency limits (concurrency-aware algorithm only)
• Rate Limit Block % - Requests blocked by rate limits
• Error Rate % - System/Redis errors
• Duration - Actual test execution time
• Latency Metrics - Detailed latency analysis of each rate limit check:
  • Latency Avg (ms) - Average latency per request
  • Latency P50 (ms) - Median latency (50th percentile)
  • Latency P95 (ms) - 95th percentile latency
  • Latency P99 (ms) - 99th percentile latency
  • Latency Max (ms) - Maximum observed latency

Latency Measurement

The stress test includes comprehensive latency measurement using high-precision microtime() to measure the added latency of each rate limit check:

Features:

• Configurable Precision: Use --latency-precision=N to set decimal places (0-10, default: 2)
• Sampling Control: Use --latency-sample=N to collect every Nth measurement (default: 1 = all measurements)
• Memory Efficient: Uses counter-based storage instead of storing individual measurements
• Detailed Statistics: Provides avg, P50, P95, P99, and max latency metrics

Examples:

Testing Modes

The stress test supports two distinct testing modes:

1. Rate Limiting Behavior Test (default): Tests how algorithms behave under controlled load with request throttling
2. Max Speed Performance Test (--max-speed): Tests raw algorithm throughput with no throttling to reveal true performance differences

Expected Performance Characteristics

SlidingWindow Algorithm:

• More accurate rate limiting, fewer burst allowances
• Higher memory usage (Redis sorted sets), slightly lower throughput
• Best for precise rate limiting requirements

FixedWindow Algorithm:

• Lower memory usage, higher throughput, simpler Redis operations
• Allows up to 2x burst at window boundaries
• Best for high-performance scenarios where some burst is acceptable

LeakyBucket Algorithm:

• Moderate memory usage, good throughput with burst accommodation
• Allows initial burst up to capacity, then enforces steady leak rate
• Best for handling traffic spikes while maintaining average rate limits
• Typically shows higher success rates in high contention scenarios

GCRA Algorithm:

• Lowest memory usage (single float per key), highest throughput (~2x faster than other algorithms)
• Uses theoretical arrival time (TAT) for precise, predictable rate limiting
• Best for high-performance, memory-constrained environments requiring smooth rate control
• Shows moderate success rates with consistent, predictable blocking behavior

Token Bucket Algorithm:

• Moderate memory usage (hash with 4 fields per key), good throughput
• Allows initial bursts up to bucket capacity, then gradual token refill
• Excellent success rates in burst scenarios, very low block rates
• Best for web APIs with bursty traffic patterns that need burst tolerance

Troubleshooting

PCNTL Extension Missing:

Redis Connection Issues: