Rate Limiting Rules

Rate limiting rules define how many requests are allowed within a given time frame. These rules are crucial for controlling access to your resources and preventing abuse or overuse of your services.

Creating Rate Limit Rules

You can create rate limit rules using the RateLimitRule class. This class provides a fluent interface for defining rules, making them easy to read and understand.

use Midnite81\Guardian\Rules\RateLimitRule;
use Midnite81\Guardian\Enums\Interval;

// Allow 100 requests per minute
$rule1 = RateLimitRule::allow(100)->perMinute();

// Allow 1000 requests per hour
$rule2 = RateLimitRule::allow(1000)->perHour();

// Allow 10000 requests per day
$rule3 = RateLimitRule::allow(10000)->perDay();

// Allow 25 requests every 3 hours
$rule4 = RateLimitRule::allow(25)->every(3, Interval::HOUR);

Available Methods

The RateLimitRule class provides several methods to define your rate limiting rules:

Static Factory Method

• allow(int $limit): Starts the rule definition with the number of allowed requests.

Time Interval Methods

• every(int $amount, Interval $unit): Defines a custom time interval.

• perSecond(): Sets the interval to one second.

• perSeconds(int $seconds): Sets the interval to a specified number of seconds.

• perMinute(): Sets the interval to one minute.

• perMinutes(int $minutes): Sets the interval to a specified number of minutes.

• perHour(): Sets the interval to one hour.

• perHours(int $hours): Sets the interval to a specified number of hours.

• perDay(): Sets the interval to one day.

• perDays(int $days): Sets the interval to a specified number of days.

• perWeek(): Sets the interval to one week.

• perWeeks(int $weeks): Sets the interval to a specified number of weeks.

• perMonth(): Sets the interval to one month.

• perMonths(int $months): Sets the interval to a specified number of months.

Expiration Methods

• dailyUntil(string $time): Sets the rule to expire daily at a specific time (format: 'H:i').

• untilMidnightTonight(): Sets the rule to expire at midnight.

• untilEndOfMonth(): Sets the rule to expire at the end of the current month.

Getter Methods

• getLimit(): Returns the number of allowed requests.

• getInterval(): Returns the interval enum value.

• getDuration(): Returns the duration of the interval.

• getUntil(): Returns the expiration time, if set.

• getTotalSeconds(): Returns the total number of seconds for the interval.

• getKey(string $prefix = '', string $suffix = ''): Generates a unique key for the rule.

Examples

Here are some more complex examples of how you can use these rules:

// Allow 500 requests per hour, resetting at midnight
$rule = RateLimitRule::allow(500)->perHour()->untilMidnightTonight();

// Allow 1000 requests per day, expiring at 23:59
$rule = RateLimitRule::allow(1000)->perDay()->dailyUntil('23:59');

// Allow 5000 requests per month, resetting at the end of each month
$rule = RateLimitRule::allow(5000)->perMonth()->untilEndOfMonth();

Using Rate Limit Rules

Once you've defined your rules, you can add them to your Guardian instance:

use Midnite81\Guardian\Factories\GuardianFactory;
use Midnite81\Guardian\Store\RedisStore;

$guardian = GuardianFactory::create(
    'my-api',
    new RedisStore($redisOptions),
    [
        RateLimitRule::allow(100)->perMinute(),
        RateLimitRule::allow(1000)->perHour(),
    ]
);

These rules will now be applied to all requests handled by this Guardian instance.

Best Practices

1. Combine rules: Use multiple rules to create more complex rate limiting strategies. For example, you might allow a high number of requests per day, but still limit the per-minute rate to prevent sudden spikes.

2. Use appropriate intervals: Choose intervals that make sense for your application. For an API, per-second or per-minute limits might be appropriate, while for a bulk operation, per-hour or per-day limits might make more sense.

3. Consider user tiers: If your application has different user tiers, you might create different sets of rules for each tier.

4. Monitor and adjust: Regularly review your rate limits and adjust them based on your application's performance and user behavior.

By effectively using rate limiting rules, you can protect your resources, ensure fair usage, and maintain the performance and reliability of your application.