Download the PHP package kartubi/php-redis-rate without Composer

PHP Redis Rate Limiter

A modern Laravel package for Redis-based rate limiting using the GCRA (Generic Cell Rate Algorithm) algorithm. Built for Laravel 10+ with PHP 8.1+ features. Inspired by and compatible with the go-redis/redis_rate library.

Looking for legacy Laravel support? Check out the v1.x branch for Laravel 5.5-9.x compatibility.

Features

• GCRA Algorithm: Uses the Generic Cell Rate Algorithm (aka leaky bucket) for precise rate limiting
• Laravel Integration: Built specifically for Laravel with service providers, facades, and middleware
• Redis Lua Scripts: Atomic operations using Redis Lua scripts for consistency
• Flexible Limits: Support for per-second, per-minute, per-hour, and custom rate limits
• Burst Support: Configure burst capacity independently from rate limits
• Modern PHP Features: Uses PHP 8.1+ features like readonly properties, named parameters, and match expressions
• Middleware Support: Ready-to-use middleware for HTTP rate limiting
• Artisan Commands: Built-in testing commands for debugging rate limits

Installation

Install the package via Composer:

For legacy Laravel projects (5.5-9.x): Use composer require kartubi/php-redis-rate:^1.0 instead.

The package will automatically register itself via Laravel's package discovery.

Publish the configuration file (optional):

Clean Redis Keys Setup (Recommended)

By default, Laravel adds an app-name prefix to Redis keys (e.g., laravel-app-database-rate:user123). For cleaner rate limiting keys, run the setup command:

This command will:

• ✅ Publish the config/redis-rate.php configuration file
• ✅ Create a self-contained Redis connection (no changes to config/database.php)
• ✅ Use a separate Redis database (default: database 2)
• ✅ Remove Laravel's app-name prefix completely
• ✅ Result in clean keys like: rate:user123

You can also specify a custom database number:

Environment Configuration

After running setup, you can optionally configure these environment variables:

Docker Configuration

For Docker environments, add these environment variables to your docker-compose.yml:

The setup command will run automatically in your Dockerfile:

Requirements

• PHP 8.1 or higher
• Laravel 10.x, 11.x, or 12.x
• Redis 3.2 or newer (requires replicate_commands feature)
• Either the Redis PHP extension or Predis 2.0+

Basic Usage

Using the Facade

Using Dependency Injection

Rate Limit Types

Pre-defined Limits

Custom Limits

Advanced Usage

Multiple Requests

Reset Rate Limits

Middleware Usage

Add the middleware to your HTTP kernel or use it directly in routes:

Register Middleware

In your app/Http/Kernel.php:

Configuration

The configuration file allows you to customize default settings:

Testing Commands

Test your rate limiting configuration:

Understanding Results

The Result object contains important information about the rate limiting decision:

Algorithm Details

This package implements the GCRA (Generic Cell Rate Algorithm), also known as the leaky bucket algorithm. GCRA provides several advantages:

• Smooth rate limiting: Distributes requests evenly over time
• Burst handling: Allows controlled bursts while maintaining average rate
• Memory efficient: Uses minimal Redis memory per key
• Atomic operations: All operations are atomic using Redis Lua scripts

Version Compatibility

Note: This is the modern v3.x version. For legacy Laravel support, see the v1.x branch documentation.

Testing

Run the test suite:

Run tests with coverage:

License

This package is open-sourced software licensed under the MIT license.

Credits

This package is inspired by the excellent go-redis/redis_rate library and implements the same GCRA algorithm for PHP/Laravel applications.