Rate Limiting

Hazaar includes a flexible rate limiting system that can be used directly in your code with Hazaar\Util\RateLimiter or attached to routes through the Hazaar\Controller\Middleware\Ratelimiter middleware. This allows you to throttle requests by IP address, user ID, API key, or any identifier you choose.

Using the RateLimiter Class

Use the Hazaar\Util\RateLimiter class when you need full control over identifiers, custom backends, or want to inspect rate limit state.

use Hazaar\Util\RateLimiter;

$limiter = new RateLimiter([
	'limit' => 60,      // Max requests
	'window' => 60,     // Window length in seconds
	'minimum' => 0,     // Minimum seconds between requests (optional)
	'backend' => 'cache',
	'backendOptions' => [
		'type' => 'shm'
	],
]);

$identifier = $request->getRemoteAddr();

if (!$limiter->check($identifier)) {
	return $this->response->tooManyRequests();
}

Options

• limit (int): Maximum number of requests allowed within the window.
• window (int): Window length in seconds.
• minimum (int): Minimum time in seconds between requests for the same identifier.
• backend (string): Backend type: cache, file, or dbi.
• backendOptions (array): Backend-specific options.

Common Methods

• check(string $identifier): bool - Returns true if the request is allowed and updates the log.
• getInfo(string $identifier): array - Returns rate limit state including attempts and remaining requests.
• getHeaders(string $identifier): array - Returns headers such as X-RateLimit-Remaining.
• delete(string $identifier): void - Clears the stored rate limit state for an identifier.

Identifiers

Rate limiting is scoped by identifier. Typical choices include:

• Remote IP address ($request->getRemoteAddr())
• Authenticated user ID
• API key or token

Pick an identifier that matches your security model and traffic patterns.

Middleware Usage

If you only need standard behavior, use the rate limiter middleware. It uses the default cache backend configured in your app settings.

You can attach it directly using the router or via middleware():

use Hazaar\Application\Router;
use Hazaar\Controller\Middleware\Ratelimiter;

Router::get('/api/user', [Api::class, 'user'])
	->middleware(new Ratelimiter(60, 60));

Hazaar also provides a convenience helper on routes:

Router::get('/api/user', [Api::class, 'user'])
	->ratelimit(60, 60);

The middleware checks the remote address and returns a RateLimitExceeded response when the limit is exceeded.

Configuring Cache Defaults (app.php)

The rate limiter middleware uses the default cache backend configured for your application. You can set this in app.php under the cache key. These settings are used by the cache-backed rate limiter when no explicit backend is provided.

return [
	'production' => [
		'cache' => [
			'backend' => 'file',
			'options' => [
				'ttl' => 3600,
			],
		],
	],
];

These cache defaults are applied automatically when you use ->ratelimit() or the Ratelimiter middleware without custom backend options.

Choosing an Approach

• Use Hazaar\Util\RateLimiter directly when you need custom identifiers, headers, or backends.
• Use Hazaar\Controller\Middleware\Ratelimiter (or ratelimit()) for simple per-route throttling with default cache configuration.