README

Forked, simplified and actualized from andrey-tm/yii2-ip-ratelimiter.

🚀 Introduction

Simple and powerful rate limiting for guest (unauthenticated) users in Yii2.

By default, Yii2's built-in RateLimiter filter heavily relies on the User component and the RateLimitInterface. This makes it unnecessarily complex — and often broken — when you need to rate-limit guests based on IP address or custom fingerprint.

This package solves that problem. It allows you to apply rate limits to guest requests without modifying your User model, without forcing authentication, and with minimal configuration.

🎯 Features

Guest‑first design – Works out of the box for unauthenticated users.
IP‑based rate limiting – Uses real client IP (supports X-Forwarded-For).
No User model changes – No need to implement getRateLimit() or loadAllowance().
Pluggable storage – Uses Yii2's cache component (Redis, Memcached, File, etc.) by default.
Standard rate limit headers – Automatically returns:
- X-Rate-Limit-Limit
- X-Rate-Limit-Remaining
- X-Rate-Limit-Reset
Customizable key – Use a custom string to generate your own fingerprint (e.g., IP + User-Agent).
PSR-12 friendly – Works with Yii2 REST and web controllers.

📦 Installation

composer require red-lolik/yii2-guest-rate-limiter

⚡ Quick Start

Configure cache component.
Make sure your application has a cache component configured (e.g., Redis, File).
The package will use Yii::$app->cache automatically.

// config/web.php
'components' => [
    'cache' => [
        'class' => 'yii\redis\Cache',
        'redis' => [
            'hostname' => 'localhost',
            'port' => 6379,
            'database' => 0,
        ],
    ],
];

Attach behavior to any controller

use RedLolik\yii2GuestRateLimiter\GuestRateLimiter;

class ApiController extends \yii\rest\Controller
{
    public function behaviors()
    {
        $behaviors = parent::behaviors();
        $behaviors['guestRateLimiter'] = [
            'class' => GuestRateLimiter::class,
            'rateLimit' => 5,
            'timePeriod' => 600,
            'actions' => ['sign-in'],
        ];

        return $behaviors;
    }
}

That's it! Guests (unauthenticated users) will now be rate-limited by their IP address.

🔧 Advanced Configuration

'guestRateLimiter' => [
    'class' => GuestRateLimiter::class,
    'cache' => 'redisCache', // Custom cache component.
    'separateUsers' => true, // ⚠️ Your UserIdentity model should implement RateLimitInterface.
    'cacheKey' => Yii::$app->request->queryString, // Custom cache key.
    'actions' => ['sign-in'], // Array of action names to which the behavior applies. Applies to all actions if empty.
    'rateLimit' => 5, // Maximum number of queries per time period.
    'timePeriod' => 600, // Time period in seconds.
]

🧪 Real-World Use Cases Identified From Developer Questions

Problem from forums / Stack Overflow	This package solution
"RateLimiter only works for logged-in users"	Works without Yii::$app->user->id
"I get 401 errors when trying to limit guests"	No authentication required
"My User model doesn't implement getRateLimit()"	No changes to User model
"Rate limiting resets across multiple servers"	Uses central cache (Redis ready)
"How to limit by IP for contact form spam?"	Ready with 3 lines of config

📋 Requirements

PHP 8.0 or later
Yii2 >= 2.0.0

🤝 Contributing

Issues and pull requests are welcome. Please report any bugs or feature requests via GitHub Issues.

📄 License

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

red-lolik / yii2-guest-rate-limiter

Maintainers

Package info

Statistics

Security