# Getting a Guardian instance

[**Guardian**](https://github.com/midnite81/guardian) instances can be obtained in several ways, with the recommended method being via Guardian factories.

## Methods to Get a Guardian Instance

1. [Factory Instances](#factory-instances)
2. [Direct Class Instantiation](#direct-class-instantiation)
3. [Dependency Injection (Laravel)](#dependency-injection-laravel)
4. [Facade (Laravel)](#facade-laravel)

## Required and Optional Arguments

The Guardian class requires the following arguments:

| Argument       | Type                                         | Description                                                 |
| -------------- | -------------------------------------------- | ----------------------------------------------------------- |
| `$identifier`  | `string`                                     | Used to register rate limits and error-handling             |
| `$cache`       | `CacheInterface`                             | Cache driver to store rate-limiting and error-handling data |
| `$rules`       | `RateLimitingRulesetInterface\|array\|null`  | Ruleset or array of `RateLimitRule` rules (optional)        |
| `$errorRules`  | `ErrorHandlingRulesetInterface\|array\|null` | Ruleset or array of `ErrorHandlingRule` rules (optional)    |
| `$cachePrefix` | `string`                                     | Prefix for cache keys (default: 'guardian')                 |

> **Note:** In Laravel's `make` method, `$cache` is not required as it defaults to Laravel's cache.

## Factory Instances

### Non-Laravel Projects

```php
use Midnite81\Guardian\Factories\GuardianFactory;
use Midnite81\Guardian\Store\FileStore;

$guardian = GuardianFactory::create(
    'weather-conditions',
    new FileStore('/path/to/cache'),
    [RateLimitRule::allow(100)->perMinute()],
    [ErrorHandlingRule::allowFailures(5)->perMinute()]
);
```

### Laravel Projects

```php
use Midnite81\Guardian\Factories\LaravelGuardianFactory;

// Using Laravel's built-in cache
$guardian = LaravelGuardianFactory::make(
    'weather-conditions',
    [RateLimitRule::allow(100)->perMinute()],
    [ErrorHandlingRule::allowFailures(5)->perMinute()]
);

// Using a custom cache
$guardian = LaravelGuardianFactory::create(
    'weather-conditions',
    new FileStore('/path/to/cache'),
    [RateLimitRule::allow(100)->perMinute()],
    [ErrorHandlingRule::allowFailures(5)->perMinute()]
);
```

## Direct Class Instantiation

```php
use Midnite81\Guardian\Guardian;
use Midnite81\Guardian\Store\FileStore;

$guardian = new Guardian(
    'spotify-playlist',
    new FileStore('/path/to/cache'),
    [RateLimitRule::allow(100)->perMinute()],
    [ErrorHandlingRule::allowFailures(5)->perMinute()]
);
```

## Dependency Injection (Laravel)

```php
use Midnite81\Guardian\Guardian;

class MyController
{
    public function __construct(protected Guardian $guardian)
    {
        $this->guardian->setIdentifier('spotify-playlist')
            ->setCache($customCache) // Optional: defaults to Laravel's cache
            ->addRules([RateLimitRule::allow(100)->perMinute()])
            ->addErrorRules([ErrorHandlingRule::allowFailures(5)->perMinute()]);
    }
}
```

## Facade (Laravel)

```php
use Midnite81\Guardian\Facades\Guardian;

// Using Laravel's built-in cache
$guardian = Guardian::make(
    'weather-conditions', 
    [RateLimitRule::allow(100)->perMinute()]
);

// Using a custom cache
$guardian = Guardian::create(
    'weather-conditions',
    new FileStore('/path/to/cache'),
    [RateLimitRule::allow(100)->perMinute()],
    [ErrorHandlingRule::allowFailures(5)->perMinute()]
);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guardian.midnite.uk/getting-started/getting-a-guardian-instance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.