Download the PHP package sanmai/rate-limiter without Composer

Rate Limiter

Cache-based API rate limiting for PHP applications.

Table of Contents

• Overview
• Features
• How It Works
• Installation
• Quick Start
  • Setting up a rate limiter
  • Tracking requests
  • Checking rate limits
  • Getting more information
• Advanced Usage
• Cache Adapters
• Technical Details
• Contributing
• License

Installation

Overview

Rate limiting with the sliding window approach.

Real-world example: Imagine you need to limit API requests to 100 per minute and 1000 per hour per client. This library lets you create a rate limiter with a 1-minute window and 1-hour observation period, then check if a client exceeds either of these limits.

Features

• Two-level limiting - Window-based and period-based limits
• Lazy evaluation - Calculates limits only when needed
• PSR-compatible - Easily integrates with PSR-15 middleware

How it works (the simple version)

This rate limiter provides two types of limits:

1. Window limits - Controls request rates in the most recent time window (e.g., 100 requests per minute)
2. Period limits - Controls total requests over a longer observation period (e.g., 1000 requests per hour)

The rate limiter itself tracks requests, while the limits are set when checking if they've been exceeded.

Quick Start

Setting up a rate limiter

Tracking requests

Checking rate limits

Getting more information

Advanced Usage

Using multiple rate limiters for different constraints

You can create different rate limiters for different types of constraints:

Self-throttling for background jobs

When you control both ends (e.g., a background job calling your own API), you can use the wait time to self-throttle instead of failing:

If you're not using DuoClock, you can use PHP's time_nanosleep() directly:

When multiple workers compete for the same rate limit, use jitter to spread out retries and avoid thundering herd:

Note on wait time calculation: The wait time assumes a uniform distribution of requests across the window. If requests are bursty (clustered at the start or end of the window), the actual required wait time may differ. For most use cases this approximation works well.

Implementing in middleware

Here's how you might implement rate limiting in a PSR-15 middleware:

Error Handling

Here are some common scenarios and how to handle them:

Cache Adapters

This library uses the cache adapters provided by the sanmai/sliding-window-counter library. For information about available adapters and how to create your own, please refer to the sliding window counter documentation.

License

See the LICENSE file for details.