Rate limiting component for Hyperf with support for multiple algorithms (Fixed Window, Sliding Window, Token Bucket, Leaky Bucket).
composer require friendsofhyperf/rate-limit- Hyperf ~3.1.0
- Redis
- 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
The easiest way to add rate limiting is using the #[RateLimit] attribute:
<?php
namespace App\Controller;
use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
use FriendsOfHyperf\RateLimit\Algorithm;
class UserController
{
/**
* Basic rate limiting: 60 attempts per 60 seconds
*/
#[RateLimit(maxAttempts: 60, decay: 60)]
public function index()
{
// Your code here
}
/**
* Using sliding window algorithm
*/
#[RateLimit(
maxAttempts: 100,
decay: 60,
algorithm: Algorithm::SLIDING_WINDOW
)]
public function api()
{
// Your code here
}
/**
* Custom key with user ID placeholder
*/
#[RateLimit(
key: 'user:{userId}:action',
maxAttempts: 10,
decay: 3600
)]
public function create($userId)
{
// Your code here
}
/**
* Using array key
*/
#[RateLimit(
key: ['user', '{userId}', 'create'],
maxAttempts: 5,
decay: 60
)]
public function update($userId)
{
// Your code here
}
/**
* Custom response message and code
*/
#[RateLimit(
maxAttempts: 5,
decay: 60,
response: 'Too many requests, please try again later.',
responseCode: 429
)]
public function login()
{
// Your code here
}
/**
* Using specific Redis pool
*/
#[RateLimit(
maxAttempts: 60,
decay: 60,
pool: 'rate_limit'
)]
public function heavyOperation()
{
// Your code here
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
key |
string|array |
'' |
Rate limit key. Supports: 'user:{user_id}', ['user', '{user_id}'], or callable |
maxAttempts |
int |
60 |
Maximum number of attempts allowed |
decay |
int |
60 |
Time window in seconds |
algorithm |
Algorithm |
Algorithm::FIXED_WINDOW |
Algorithm to use: fixed_window, sliding_window, token_bucket, leaky_bucket |
pool |
?string |
null |
The Redis connection pool to use |
response |
string |
'Too Many Attempts.' |
Custom response when rate limit is exceeded |
responseCode |
int |
429 |
HTTP response code when rate limit is exceeded |
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:
<?php
use FriendsOfHyperf\RateLimit\Annotation\RateLimit;
use FriendsOfHyperf\RateLimit\Annotation\AutoSort;
class ApiController
{
/**
* Multiple rate limits with smart prioritization
* Stricter limits (smaller maxAttempts/decay ratio) are evaluated first
*/
#[AutoSort]
#[RateLimit(maxAttempts: 10, decay: 60)] // 10 requests/minute - evaluated first
#[RateLimit(maxAttempts: 100, decay: 3600)] // 100 requests/hour - evaluated second
public function expensiveOperation()
{
// Your code here
}
/**
* Without AutoSort, rate limits are evaluated in declaration order
*/
#[RateLimit(maxAttempts: 100, decay: 3600)] // Evaluated first
#[RateLimit(maxAttempts: 10, decay: 60)] // Evaluated second
public function anotherOperation()
{
// Your code here
}
}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
AutoSortis explicitly used - Backward Compatible: Existing code continues to work without changes
The key parameter supports dynamic placeholders that will be replaced with method arguments:
// Named placeholders
#[RateLimit(key: 'user:{userId}:{action}')]
public function action($userId, $action)
// Array format (automatically joined with ':')
#[RateLimit(key: ['user', '{userId}', '{action}'])]
public function action($userId, $action)For HTTP requests, you can create custom middleware extending RateLimitMiddleware:
<?php
namespace App\Middleware;
use FriendsOfHyperf\RateLimit\Middleware\RateLimitMiddleware;
use FriendsOfHyperf\RateLimit\Algorithm;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
class ApiRateLimitMiddleware extends RateLimitMiddleware
{
// Override default properties
protected int $maxAttempts = 100;
protected int $decay = 60;
protected Algorithm $algorithm = Algorithm::SLIDING_WINDOW;
protected string $responseMessage = 'API rate limit exceeded';
protected int $responseCode = 429;
// Or customize key resolution
protected function resolveKey(ServerRequestInterface $request): string
{
return 'api:' . $this->getClientIp();
}
}Then register the middleware in your config:
// config/autoload/middlewares.php
return [
'http' => [
App\Middleware\ApiRateLimitMiddleware::class,
],
];Simplest algorithm, counts requests in fixed time windows.
#[RateLimit(algorithm: Algorithm::FIXED_WINDOW)]Pros: Simple, memory efficient Cons: Can allow burst requests at window boundaries
More accurate than fixed window, spreads requests evenly.
#[RateLimit(algorithm: Algorithm::SLIDING_WINDOW)]Pros: Smooths out bursts, more accurate Cons: Slightly more complex
Allows burst traffic while maintaining average rate.
#[RateLimit(algorithm: Algorithm::TOKEN_BUCKET)]Pros: Allows burst traffic, flexible Cons: Requires more configuration
Processes requests at constant rate, queues bursts.
#[RateLimit(algorithm: Algorithm::LEAKY_BUCKET)]Pros: Smooth output rate, prevents bursts Cons: Can delay requests
You can implement your own rate limiter by implementing RateLimiterInterface:
<?php
namespace App\RateLimit;
use FriendsOfHyperf\RateLimit\Contract\RateLimiterInterface;
class CustomRateLimiter implements RateLimiterInterface
{
public function tooManyAttempts(string $key, int $maxAttempts, int $decay): bool
{
// Your implementation
}
public function availableIn(string $key): int
{
// Your implementation
}
public function remaining(string $key, int $maxAttempts): int
{
// Your implementation
}
}When rate limit is exceeded, a RateLimitException is thrown:
<?php
try {
$userController->index();
} catch (FriendsOfHyperf\RateLimit\Exception\RateLimitException $e) {
// Rate limit exceeded
$message = $e->getMessage(); // "Too Many Attempts. Please try again in X seconds."
$code = $e->getCode(); // 429
}The component uses Hyperf's Redis configuration. You can specify which Redis pool to use in the annotation or middleware:
// Using specific Redis pool
#[RateLimit(pool: 'rate_limit')]Make sure to configure your Redis pool in config/autoload/redis.php:
return [
'default' => [
'host' => env('REDIS_HOST', 'localhost'),
'port' => env('REDIS_PORT', 6379),
'auth' => env('REDIS_AUTH', null),
'db' => 0,
'pool' => [
'min_connections' => 1,
'max_connections' => 30,
],
],
'rate_limit' => [
'host' => env('REDIS_HOST', 'localhost'),
'port' => env('REDIS_PORT', 6379),
'auth' => env('REDIS_AUTH', null),
'db' => 1,
'pool' => [
'min_connections' => 5,
'max_connections' => 50,
],
],
];Limit login attempts to prevent brute force attacks:
#[RateLimit(
key: 'login:{email}',
maxAttempts: 5,
decay: 300, // 5 minutes
response: 'Too many login attempts. Please try again after 5 minutes.',
responseCode: 429
)]
public function login(string $email, string $password)
{
// Login logic here
}Different rate limits for different API endpoints:
class ApiController
{
// Public API: 100 requests per minute
#[RateLimit(maxAttempts: 100, decay: 60)]
public function public()
{
// Public endpoint
}
// Premium API: 1000 requests per minute
#[RateLimit(maxAttempts: 1000, decay: 60)]
public function premium()
{
// Premium endpoint
}
}Rate limit per user:
#[RateLimit(
key: ['user', '{userId}', 'action'],
maxAttempts: 10,
decay: 3600 // 1 hour
)]
public function performAction(int $userId)
{
// Action logic here
}Rate limit by IP address using middleware:
class IpRateLimitMiddleware extends RateLimitMiddleware
{
protected function resolveKey(ServerRequestInterface $request): string
{
return 'ip:' . $this->getClientIp();
}
}Use AutoSort to efficiently handle multiple rate limits on expensive operations:
class ReportController
{
/**
* Expensive report generation with multiple protection levels
* AutoSort ensures stricter limits are checked first for better performance
*/
#[AutoSort]
#[RateLimit(maxAttempts: 5, decay: 60, response: 'Too many requests. Max 5 per minute')] // Emergency brake
#[RateLimit(maxAttempts: 30, decay: 3600, response: 'Hourly limit exceeded. Max 30 per hour')] // Sustained load
#[RateLimit(maxAttempts: 100, decay: 86400, response: 'Daily limit exceeded. Max 100 per day')] // Daily cap
public function generateReport($reportType)
{
// Expensive report generation logic here
}
}