> For the complete documentation index, see [llms.txt](https://guardian.midnite.uk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.midnite.uk/getting-started/getting-a-guardian-instance.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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