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

1. 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,
        ],
    ],
];

1. 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

📋 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.