Redis-Based Rate Limiting in PHP: Implementation Guide

API abuse is one of the most common causes of unexpected downtime and degraded performance in PHP applications. When clients send too many requests, servers strain under the load, legitimate users experience slow response times, and infrastructure costs climb rapidly. Redis-based rate limiting gives PHP applications a reliable way to control request rates across multiple servers while keeping latency low and implementation straightforward.

Why Redis Works Well for Rate Limiting

Redis is a single-threaded, in-memory data store that processes commands atomically. Because every operation completes without interference from other clients, it handles concurrent requests reliably. When two requests arrive at the same moment and both try to increment the same counter, Redis processes one after the other and records both increments correctly.

A PHP variable used as a counter does not persist across processes or multiple servers. A MySQL row used as a counter creates row-level locks under concurrent writes. Redis avoids both problems by keeping counter state in shared memory that every PHP server in a cluster can access. The performance benefit is significant: a Redis rate limit check typically completes in under one millisecond, adding negligible latency when the limit is not exceeded. When the limit is exceeded, returning a 429 response immediately is the correct behaviour since the request would have been refused anyway.

PHP applications that serve APIs, handle webhooks, or expose any kind of programmatic interface benefit from Redis rate limiting. The setup is lightweight enough for small projects and scales well for high-traffic applications.

Understanding the Sliding Window Algorithm

The simplest rate limiting approach uses a fixed window: allow a set number of requests per hour, then reset the counter at the start of each hour. The problem with fixed windows is that a client can make 100 requests at 11:59 and another 100 requests at 12:01, effectively hitting 200 requests in two minutes without violating the limit.

The sliding window algorithm solves this by tracking requests in time-ordered buckets and calculating the sum of requests within the most recent time window. A client that makes 80 requests at 11:58 and another 80 at 12:02 will be rate-limited because the window covering 12:00 to 12:02 shows more than 100 requests. This provides a smoother and fairer rate limit that prevents burst abuse.

The implementation uses a Redis sorted set, where each entry stores a request timestamp as both the score and value. Before processing a new request, the code removes all entries older than the window, counts what remains, and allows or blocks the request accordingly.

class SlidingWindowRateLimiter {
    private Redis $redis;
    private string $key;
    private int $maxRequests;
    private int $windowSeconds;

    public function __construct(
        Redis $redis,
        string $key,
        int $maxRequests,
        int $windowSeconds
    ) {
        $this->redis = $redis;
        $this->key = $key;
        $this->maxRequests = $maxRequests;
        $this->windowSeconds = $windowSeconds;
    }

    public function isAllowed(string $clientId): bool {
        $now = microtime(true);
        $windowStart = $now - $this->windowSeconds;
        $fullKey = "ratelimit:{$this->key}:{$clientId}";

        // Remove expired entries from the sorted set
        $this->redis->zRemRangeByScore($fullKey, '-inf', (string)$windowStart);

        // Count current requests within the window
        $currentCount = $this->redis->zCard($fullKey);

        if ($currentCount >= $this->maxRequests) {
            return false;
        }

        // Add the new request with current timestamp
        $this->redis->zAdd($fullKey, $now, $now . ':' . uniqid());

        // Set expiry so the key auto-cleans if no requests arrive
        $this->redis->expire($fullKey, $this->windowSeconds + 1);

        return true;
    }

    public function getRetryAfter(string $clientId): int {
        $fullKey = "ratelimit:{$this->key}:{$clientId}";
        $oldest = $this->redis->zRange($fullKey, 0, 0, true);

        if (empty($oldest)) {
            return 0;
        }

        $oldestTimestamp = (float)key($oldest);
        return (int)ceil($oldestTimestamp + $this->windowSeconds - $now);
    }
}

The sorted set naturally expires old entries, and the key expiry ensures cleanup even when traffic stops. If you want to explore different rate limiting approaches and when each works best, a practical overview of API rate limiting patterns covers throttling strategies alongside rate limiting.

Token Bucket Rate Limiting for Bursty Traffic

The sliding window algorithm is effective, but the token bucket algorithm is better suited for APIs where burst traffic is legitimate. In a token bucket setup, a client accumulates tokens at a steady rate, each request consumes a token, and requests are refused when no tokens are available.

For example, an API might allow 100 requests per minute on average but permit a client to burst up to 20 requests at once. The bucket refills continuously, so a client that has not made requests recently can make a burst of calls before being throttled back to the sustained rate.

The implementation uses a Lua script to perform the check and decrement atomically. Without atomicity, there would be a window between reading the token count and decrementing it where another request could slip through and exceed the limit.

class TokenBucketRateLimiter {
    private Redis $redis;
    private string $key;
    private int $bucketCapacity;
    private float $refillRatePerSecond;

    public function __construct(
        Redis $redis,
        string $key,
        int $bucketCapacity,
        float $refillRatePerSecond
    ) {
        $this->redis = $redis;
        $this->key = $key;
        $this->bucketCapacity = $bucketCapacity;
        $this->refillRatePerSecond = $refillRatePerSecond;
    }

    public function consume(string $clientId, int $tokens = 1): bool {
        $fullKey = "tokenbucket:{$this->key}:{$clientId}";

        $lua = <<<'LUA'
local key = KEYS[1]
local capacity = tonumber(ARGV[1])
local refill_rate = tonumber(ARGV[2])
local now = tonumber(ARGV[3])
local requested = tonumber(ARGV[4])

local bucket_data = redis.call('HMGET', key, 'tokens', 'last_refill')
local available_tokens = tonumber(bucket_data[1]) or capacity
local last_refill = tonumber(bucket_data[2]) or now

-- Refill tokens based on elapsed time
local elapsed = now - last_refill
available_tokens = math.min(capacity, available_tokens + (elapsed * refill_rate))

if available_tokens >= requested then
    available_tokens = available_tokens - requested
    redis.call('HMSET', key, 'tokens', available_tokens, 'last_refill', now)
    redis.call('EXPIRE', key, 3600)
    return 1
else
    return 0
end
LUA;

        $result = $this->redis->eval(
            $lua,
            1,
            $fullKey,
            $this->bucketCapacity,
            $this->refillRatePerSecond,
            microtime(true),
            $tokens
        );

        return (bool)$result;
    }
}

Redis executes Lua scripts atomically. Nothing else runs while the script executes, which eliminates race conditions even under heavy concurrent load.

Applying Rate Limits to Different Client Identifiers

Rate limits can be scoped to different identifiers depending on your threat model and API design. The most common approaches are per IP address, per API key, or per authenticated user.

// Rate limiting by IP for public endpoints
$clientIp = $_SERVER['REMOTE_ADDR'] ?? 'unknown';
$limiter = new SlidingWindowRateLimiter($redis, 'api_ip', 30, 60);
$allowed = $limiter->isAllowed($clientIp);

// Rate limiting by API key for authenticated clients
$authHeader = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$apiKey = preg_replace('/^Bearer\s+/i', '', $authHeader);
$limiter = new SlidingWindowRateLimiter($redis, 'api_key', 500, 60);
$allowed = $limiter->isAllowed($apiKey);

// Rate limiting by user ID for logged-in sessions
$userId = $_SESSION['user_id'] ?? $payload['sub'] ?? null;
$limiter = new SlidingWindowRateLimiter($redis, 'api_user', 100, 60);
$allowed = $limiter->isAllowed($userId);

Most REST APIs apply different limits to different endpoint types. Unauthenticated endpoints typically receive stricter limits, such as 30 requests per minute per IP address. Authenticated endpoints get more generous limits, such as 500 requests per minute per API key. Internal endpoints may have very high limits that prevent accidental overload rather than intentional abuse.

Sending the Correct HTTP Response When Limits Are Exceeded

When a rate limit is exceeded, the correct HTTP status code is 429 Too Many Requests. The response should include a Retry-After header that tells the client how many seconds to wait before trying again. Adding an X-RateLimit-Remaining header to successful responses helps clients track their remaining quota.

if (!$limiter->isAllowed($clientId)) {
    $retryAfter = $limiter->getRetryAfter($clientId);

    http_response_code(429);
    header('Content-Type: application/json');
    header('Retry-After: ' . $retryAfter);
    header('X-RateLimit-Remaining: 0');
    header('X-RateLimit-Limit: ' . $maxRequests);

    echo json_encode([
        'error' => 'Too Many Requests',
        'message' => 'Rate limit exceeded. Please retry after ' . $retryAfter . ' seconds.',
        'retry_after' => $retryAfter
    ], JSON_PRETTY_PRINT);
    exit;
}

Returning the correct status code and headers allows API clients to implement backoff correctly. Most HTTP client libraries recognise the Retry-After header and will automatically retry with exponential backoff when they receive a 429 response.

Integrating Rate Limiting in PHP Applications

In Laravel, rate limiting middleware can apply the Redis-backed limiter to specific routes or route groups. The middleware runs before the request reaches your controller, which means expensive computation only happens for allowed requests.

use Closure;
use Illuminate\Http\Request;

Route::middleware(function (Request $request, Closure $next) {
    $redis = app(Redis::class);
    $authHeader = $request->header('Authorization') ?? '';
    $apiKey = preg_replace('/^Bearer\s+/i', '', $authHeader);

    $limiter = new SlidingWindowRateLimiter($redis, 'api', 500, 60);

    if (!$limiter->isAllowed($apiKey)) {
        return response()->json([
            'error' => 'Too Many Requests',
            'message' => 'Rate limit exceeded.'
        ], 429)->withHeaders([
            'Retry-After' => $limiter->getRetryAfter($apiKey),
            'X-RateLimit-Limit' => 500
        ]);
    }

    return $next($request);
});

In plain PHP without a framework, include the rate limiter class in a central bootstrap file or front controller. The critical point is calling the limiter before any significant computation or database queries happen. Rate limiting that fires after the expensive work is done defeats the purpose entirely.

Avoiding Common Implementation Mistakes

Non-atomic rate limiting is the most common implementation error. A flawed approach reads the counter, checks if it is under the limit, then writes the incremented value. Under concurrent requests, two requests can both read the same counter, both pass the check, both increment, and both succeed. The rate limit is effectively broken. Always use Redis atomic operations such as MULTI/EXEC transactions, Lua scripts, or the built-in INCR command.

Using a single global rate limit key across all clients is the second most common mistake. If one client consumes all available capacity, every other client gets blocked. Always scope the rate limit key to the individual client using the IP address, API key, or user ID.

The third mistake is not handling Redis unavailability. If the Redis connection fails and the rate limiter throws an exception, every request fails. The correct approach when the rate limiting store is unavailable is usually to allow the request through while logging a warning. This fail-open strategy prefers availability over the rate limit, which is appropriate for most APIs. For payment processing or security-critical endpoints, a fail-closed approach that returns 503 Service Unavailable may be more suitable.

Testing Your Rate Limiting Implementation

Once the rate limiter is implemented, test it under realistic conditions before relying on it in production. Check that concurrent requests from the same client are counted correctly. Verify that the 429 response includes the correct Retry-After value. Confirm that rate limits reset properly after the time window passes.

Automated tests should cover the core limiter logic directly, independent of Redis, by mocking the Redis client. Integration tests should run against a real Redis instance or a containerised Redis setup to catch any issues with atomicity or key management.

Putting It Together

Redis-based rate limiting in PHP solves the problems that make other approaches unreliable: race conditions, write contention, and state that does not survive across servers. The sliding window algorithm provides fair, accurate limiting that prevents burst abuse, while the token bucket algorithm accommodates legitimate traffic spikes. Atomic operations via Lua scripts and proper key scoping ensure the implementation holds up under concurrent load.

The key decisions are choosing the right algorithm for your traffic pattern, scoping limits to the correct identifier, returning standard HTTP responses, and handling Redis failures gracefully. Once the rate limiter is in place and tested, it runs with minimal overhead and protects your application infrastructure from both accidental misconfiguration and deliberate abuse.

If you are building or maintaining a PHP API and want a practical review of your current rate limiting setup, prepare details of your current implementation, the frameworks you use, and your expected traffic volumes before getting in touch.