Download the PHP package friendsofhyperf/rate-limit without Composer

Rate Limit

Rate limiting component for Hyperf with support for multiple algorithms (Fixed Window, Sliding Window, Token Bucket, Leaky Bucket).

Installation

Requirements

• Hyperf ~3.1.0
• Redis

Features

• Multiple Rate Limiting Algorithms
  • Fixed Window
  • Sliding Window
  • Token Bucket
  • Leaky Bucket
• Flexible Usage
  • Annotation-based rate limiting via Aspect
  • Custom middleware support
• Smart Order for Multiple Annotations
  • Automatic prioritization of multiple RateLimit annotations
  • Intelligent ordering by strictness (maxAttempts/decay ratio)
  • More restrictive limits evaluated first for better performance
• Flexible Key Generation
  • Default method/class-based keys
  • Custom key with placeholders support
  • Array keys support
  • Callable keys support
• Customizable Responses
  • Custom response message
  • Custom HTTP response code
• Multi Redis Pool Support

Usage

Method 1: Using Annotation

The easiest way to add rate limiting is using the #[RateLimit] attribute:

Annotation Parameters

Multiple RateLimits with AutoSort

When you need multiple rate limits on the same method (e.g., per-minute and per-hour limits), you can use the AutoSort annotation to automatically prioritize them:

Benefits of AutoSort:

• Performance: Stricter limits are checked first, avoiding unnecessary checks of more lenient limits
• Intelligence: Automatically calculates priority based on limit strictness (maxAttempts/decay ratio)
• Opt-in: Only affects methods where AutoSort is explicitly used
• Backward Compatible: Existing code continues to work without changes

Key Placeholders

The key parameter supports dynamic placeholders that will be replaced with method arguments:

Method 2: Using Middleware

For HTTP requests, you can create custom middleware extending RateLimitMiddleware:

Then register the middleware in your config:

Rate Limiting Algorithms

Fixed Window (默认)

Simplest algorithm, counts requests in fixed time windows.

Pros: Simple, memory efficient Cons: Can allow burst requests at window boundaries

Sliding Window

More accurate than fixed window, spreads requests evenly.

Pros: Smooths out bursts, more accurate Cons: Slightly more complex

Token Bucket

Allows burst traffic while maintaining average rate.

Pros: Allows burst traffic, flexible Cons: Requires more configuration

Leaky Bucket

Processes requests at constant rate, queues bursts.

Pros: Smooth output rate, prevents bursts Cons: Can delay requests

Custom Rate Limiter

You can implement your own rate limiter by implementing RateLimiterInterface:

Exception Handling

When rate limit is exceeded, a RateLimitException is thrown:

Configuration

The component uses Hyperf's Redis configuration. You can specify which Redis pool to use in the annotation or middleware:

Make sure to configure your Redis pool in config/autoload/redis.php:

Examples

Example 1: Login Rate Limiting

Limit login attempts to prevent brute force attacks:

Example 2: API Endpoint Rate Limit

Different rate limits for different API endpoints:

Example 3: User-based Rate Limiting

Rate limit per user:

Example 4: IP-based Rate Limiting

Rate limit by IP address using middleware:

Example 5: Multiple Rate Limits with Smart Order

Use AutoSort to efficiently handle multiple rate limits on expensive operations:

License

MIT