What are rulesets

Rulesets in Guardian allow you to define a series of rules for Rate-Limiting and Error-Handling. Instead of defining rules each time you construct a Guardian instance, you can create pre-determined sets of rules to pass to Guardian. This approach promotes code reusability and cleaner organization of your rate limiting and error handling logic.

Types of Rulesets

Guardian supports two types of rulesets:

1. Rate Limiting Rulesets

2. Error Handling Rulesets

Both types of rulesets require you to implement a rules() method, but they differ in the type of rules they return:

• Rate Limiting Rulesets return an array of RateLimitRule objects

• Error Handling Rulesets return an array of ErrorHandlingRule objects

Implementing Rate Limiting Rulesets

To create a Rate Limiting Ruleset, your class must implement the Midnite81\Guardian\Contracts\Rulesets\RateLimitingRulesetInterface. However, for convenience, you can extend the Midnite81\Guardian\Rulesets\AbstractRateLimitingRuleset class, which implements the interface and provides core logic.

Here's an example of a custom Rate Limiting Ruleset:

<?php

declare(strict_types=1);

namespace App\Rulesets;

use Midnite81\Guardian\Rulesets\AbstractRateLimitingRuleset;
use Midnite81\Guardian\Rules\RateLimitRule;

class MyCustomRateLimitingRuleset extends AbstractRateLimitingRuleset
{
    /**
     * {@inheritDoc}
     */
    public function rules(): array
    {
        return [
            RateLimitRule::allow(20)->perHour(),
            RateLimitRule::allow(1000)->perDay(),
        ];
    }
}

Implementing Error Handling Rulesets

For Error Handling Rulesets, your class must implement the Midnite81\Guardian\Contracts\Rulesets\ErrorHandlingRulesetInterface. Similar to Rate Limiting Rulesets, you can extend the Midnite81\Guardian\Rulesets\AbstractErrorHandlingRuleset for convenience.

Here's an example of a custom Error Handling Ruleset:

<?php

declare(strict_types=1);

namespace App\Rulesets;

use Midnite81\Guardian\Rulesets\AbstractErrorHandlingRuleset;
use Midnite81\Guardian\Rules\ErrorHandlingRule;

class MyCustomErrorHandlingRuleset extends AbstractErrorHandlingRuleset
{
    /**
     * {@inheritDoc}
     */
    public function rules(): array
    {
        return [
            ErrorHandlingRule::allowFailures(5)->perHour(),
        ];
    }
}

Using Custom Rulesets with Guardian

You can use your custom rulesets with Guardian in two ways:

1. Pass the ruleset when creating the Guardian instance:

use App\Rulesets\MyCustomRateLimitingRuleset;
use App\Rulesets\MyCustomErrorHandlingRuleset;
use Midnite81\Guardian\Factories\GuardianFactory;
use Midnite81\Guardian\Store\RedisStore;

$guardian = GuardianFactory::create(
    'my-api',
    new RedisStore($options),
    new MyCustomRateLimitingRuleset(),
    new MyCustomErrorHandlingRuleset()
);

1. Set the rulesets after creating the Guardian instance:

$guardian->setRules(new MyCustomRateLimitingRuleset());
$guardian->setErrorRules(new MyCustomErrorHandlingRuleset());

Adding Additional Rules to a Guardian Instance

In some cases, you might want to add additional rules to a specific Guardian instance without modifying the original ruleset. Guardian provides methods to add rules dynamically:

Adding Rate Limiting Rules

You can use the addRules() method to add one or more rate limiting rules to an existing Guardian instance:

use Midnite81\Guardian\Rules\RateLimitRule;

$guardian->addRules([
    RateLimitRule::allow(5)->perMinute(),
    RateLimitRule::allow(100)->perHour(),
]);

Adding Error Handling Rules

Similarly, you can use the addErrorRules() method to add one or more error handling rules:

use Midnite81\Guardian\Rules\ErrorHandlingRule;

$guardian->addErrorRules([
    ErrorHandlingRule::allowFailures(3)->perMinute(),
]);

These methods are useful when you need to:

1. Add context-specific rules for a particular Guardian instance.

2. Dynamically adjust rules based on runtime conditions.

3. Temporarily modify the ruleset for specific operations without affecting the original ruleset.

Remember that rules added this way only apply to the specific Guardian instance and do not modify the original ruleset.

Benefits of Using Rulesets

1. Reusability: Define rules once and reuse them across multiple Guardian instances.

2. Organization: Keep your rate limiting and error handling logic separate from your main application code.

3. Flexibility: Easily switch between different sets of rules for different scenarios or environments.

4. Maintainability: Update rules in one place, affecting all Guardian instances using that ruleset.

5. Customization: Ability to add instance-specific rules when needed, without modifying the base ruleset.

By leveraging rulesets and the ability to add rules dynamically, you can create more modular, maintainable, and flexible rate limiting and error handling strategies in your application.