Saloon

https://docs.saloon.dev
Admin
Saloon is a PHP library designed for rapidly building and testing third-party API integrations and...
Tokens:42,729
Snippets:588
Trust Score:4.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install pagination plugin

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Use Composer to install the Saloon pagination plugin package.

```sh
composer require saloonphp/pagination-plugin "^2.0"
```

--------------------------------

### Install Saloon Cache Plugin

Source: https://docs.saloon.dev/installable-plugins/caching-responses.md

Install the required caching plugin via Composer.

```bash
composer require saloonphp/cache-plugin "^3.0"
```

--------------------------------

### Install Saloon SDK Generator

Source: https://docs.saloon.dev/installable-plugins/sdk-generator.md

Use Composer to install the generator globally on your machine.

```sh
composer global require crescat-io/saloon-sdk-generator
```

--------------------------------

### Configure Cache Drivers

Source: https://docs.saloon.dev/installable-plugins/caching-responses.md

Examples of configuring different cache drivers for Saloon requests.

```php
use Saloon\CachePlugin\Drivers\PsrCacheDriver;

public function resolveCacheDriver(): Driver
{
    // This example uses the PhpArrayAdapter from 
    // the symfony/cache library.
    
    return new PsrCacheDriver(new PhpArrayAdapter);
}
```

```php
use Saloon\CachePlugin\Drivers\FlysystemDriver;

public function resolveCacheDriver(): Driver
{
    // This example uses the "AwsS3V3Adapter" driver
    // that is provided by Flysystem.

    return new FlysystemDriver(
        new Filesystem(new AwsS3V3Adapter($s3Client, 'bucket-name'))
    );
}
```

```php
use Illuminate\Support\Facades\Cache;
use Saloon\CachePlugin\Drivers\LaravelCacheDriver;

public function resolveCacheDriver(): Driver
{
    // This example uses Redis cache store that
    // Laravel provides.

    return new LaravelCacheDriver(Cache::store('redis'));
}
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://docs.saloon.dev/llms.txt

Perform an HTTP GET request to the documentation index using the 'ask' and 'goal' parameters to receive a direct answer and relevant excerpts.

```http
GET https://docs.saloon.dev/installable-plugins/laravel-integration.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Installing Collections Support

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Install the illuminate/collections package via Composer to enable LazyCollection support if not using Laravel.

```bash
composer require illuminate/collections
```

--------------------------------

### Install Saloon Laravel Plugin

Source: https://docs.saloon.dev/installable-plugins/laravel-integration.md

Install the plugin via Composer. Ensure saloonphp/saloon is already a dependency.

```bash
composer require saloonphp/laravel-plugin "^4.0"
```

--------------------------------

### Install Lawman via Composer

Source: https://docs.saloon.dev/installable-plugins/lawman.md

Install the Lawman plugin as a development dependency.

```bash
composer require jonpurvis/lawman --dev
```

--------------------------------

### Install Symfony Var Dumper

Source: https://docs.saloon.dev/the-basics/debugging.md

Install the required dependency for Saloon's default debugging driver if not using Laravel.

```bash
composer require symfony/var-dumper
```

--------------------------------

### Example XML Data Structure

Source: https://docs.saloon.dev/installable-plugins/xml-wrangler.md

Sample XML structure representing a breakfast menu used for demonstration purposes.

```xml
<breakfast_menu>
  <food soldOut="false" bestSeller="true">
    <name>Belgian Waffles</name>
    <price>$5.95</price>
    <description>Two of our famous Belgian Waffles with plenty of real maple syrup</description>
    <calories>650</calories>
  </food>
  <food soldOut="false" bestSeller="false">
    <name>Strawberry Belgian Waffles</name>
    <price>$7.95</price>
    <description>Light Belgian waffles covered with strawberries and whipped cream</description>
    <calories>900</calories>
  </food>
  <food soldOut="false" bestSeller="true">
    <name>Berry-Berry Belgian Waffles</name>
    <price>$8.95</price>
    <description>Light Belgian waffles covered with an assortment of fresh berries and whipped cream</description>
    <calories>900</calories>
  </food>
</breakfast_menu>
```

--------------------------------

### Install Saloon via Composer

Source: https://docs.saloon.dev/the-basics/installation.md

Use this command to add the Saloon package to your project dependencies.

```bash
composer require saloonphp/saloon "^4.0"
```

--------------------------------

### Install Rate Limit Plugin

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Use Composer to add the rate limit plugin to your project.

```bash
composer require saloonphp/rate-limit-plugin "^2.0"
```

--------------------------------

### Defining test fixture paths

Source: https://docs.saloon.dev/upgrade/upgrading-from-v3-to-v4.md

Example of setting a fixture path in a test, now restricted against path traversal in v4.

```php
<?php

test('can store servers in the database from laravel forge', function () {
    MockClient::global([
        GetServersRequest::class => MockResponse::fixture('custom-path/servers'),
    ]);
});
```

```php
MockResponse::fixture('../../custom-path/servers'); ⛔️
MockResponse::fixture('~/custom-path/servers'); ⛔️
```

--------------------------------

### Provide requests using a callable or invokable class

Source: https://docs.saloon.dev/digging-deeper/concurrency-and-pools.md

Use a callable or an invokable class to return requests, allowing for dynamic logic before the pool starts.

```php
<?php

$callback = function () {
    return [
        new GetServersRequest,
        new GetSitesRequest,
        new GetUserRequest,
    ];
};

$forge = new Forge;
$pool = $forge->pool($callback);

// or

$pool->setRequests($callback);
```

```php
<?php

class PoolClass {
    public function __invoke() {
        return [
            new GetServersRequest,
            new GetSitesRequest,
            new GetUserRequest,
        ];
    }
}

$forge = new ForgeConnector;
$pool = $forge->pool(new PoolClass);
```

--------------------------------

### Implement ClientCredentialsGrant Trait

Source: https://docs.saloon.dev/digging-deeper/oauth2-authentication/client-credentials-grant.md

Basic setup for adding the ClientCredentialsGrant trait to a Saloon connector.

```php
<?php

use Saloon\Http\Connector;
use Saloon\Traits\OAuth2\ClientCredentialsGrant;

class WarehouseConnector extends Connector
{
    use ClientCredentialsGrant;
}
```

--------------------------------

### Add AuthorizationCodeGrant Trait

Source: https://docs.saloon.dev/digging-deeper/oauth2-authentication/oauth2-authentication.md

Initial setup for a connector to support the Authorization Code Flow by adding the required trait.

```php
<?php

use Saloon\Http\Connector;
use Saloon\Traits\OAuth2\AuthorizationCodeGrant;

class SpotifyConnector extends Connector;
{
    use AuthorizationCodeGrant;
}
```

--------------------------------

### Initializing a Request Pool

Source: https://docs.saloon.dev/digging-deeper/concurrency-and-pools.md

Shows how to instantiate a pool with optional parameters and execute the requests.

```php
<?php

$forge = new ForgeConnector;

// Pool has various optional parameters if you want to set them here...

$pool = $forge->pool(
    requests: [],
    concurrency: 5,
    responseHandler: function () { ... },
    exceptionHandler: function () { ... },
);

// Initiate the transfer of requests

$promise = $pool->send();

// Force all the requests to be fulfilled

$promise->wait();
```

--------------------------------

### Instantiate the SDK

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Initialize the SDK connector by providing the required API token.

```php
<?php

use Pokeapi\Pokeapi;

$pokeapi = new Pokeapi('my-api-token');

// Ready to make requests!
```

--------------------------------

### Automating Authentication via Connector Boot

Source: https://docs.saloon.dev/conclusion/how-to-guides/per-request-authentication.md

Refactoring authentication logic into the connector's boot method to handle token retrieval automatically before requests.

```php
<?php

use Saloon\Http\PendingRequest;
use Saloon\Http\Auth\TokenAuthenticator;

class MusicApi extends Connector
{
    // You should move any authentication requirements into the constructor
    // of the connector so your users have to provide the authentication
    // requirements before instantiating the connector.

    public function __construct(
        protected string $username,
        protected string $password,
    )
    {
        //
    }
    
    public function boot(PendingRequest $pendingRequest): void
    {
        // Let's start by returning early if the request being sent is the
        // GetAccessTokenRequest. We don't want to create an infinite loop
    
        if ($pendingRequest->getRequest() instanceof GetAccessTokenRequest) {
            return;
        }
        
        // Now let's make our authentication request. Since we are in the
        // context of the connector, we can just simply call $this and
        // make another request!
        
        $authResponse = $this->send(new GetAccessTokenRequest($this->username, $this->password));
        
        // Now we'll take the token from the auth response and then pass it
        // into the $pendingRequest which is the original GetSongsByArtistRequest.
        
        $pendingRequest->authenticate(new TokenAuthenticator($authResponse->json()['token']));
    }
}
```

--------------------------------

### Namespace fixtures with folders

Source: https://docs.saloon.dev/the-basics/testing.md

Organizes fixtures into subdirectories using forward slashes in the fixture name.

```php
MockClient::global([
   GetServersRequest::class => MockResponse::fixture('forge/servers'),
]);
```

--------------------------------

### Defining Instagram connector and request

Source: https://docs.saloon.dev/upgrade/upgrading-from-v3-to-v4.md

Example of a connector and request structure where user input in the endpoint could lead to unintended URL overrides.

```php
// Connector

class InstagramConnector extends Connector
{
    public function resolveBaseUrl(): string
    {
        return 'https://instagram.com';
    }
}

// Request

class GetProfileRequest extends Request
{
    public function resolveEndpoint(): string
    {
        return $this->handle;
    }
}
```

--------------------------------

### Instantiating a Paginator

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Create a paginator instance by calling the paginate method on a connector with a request. Requests are deferred until iteration begins.

```php
<?php

$spotifyConnector = new SpotifyConnector;

$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);
```

--------------------------------

### Publish Saloon Configuration

Source: https://docs.saloon.dev/installable-plugins/laravel-integration.md

Publish the configuration file using the Artisan command.

```bash
php artisan vendor:publish --tag=saloon-config
```

--------------------------------

### Defining a fully qualified URL in resolveEndpoint

Source: https://docs.saloon.dev/upgrade/upgrading-from-v3-to-v4.md

Example of the legacy behavior where a fully qualified URL in resolveEndpoint overrides the connector's base URL.

```php
<?php

class GetServersRequest extends Request
{
    protected Method $method = Method::GET;

    public function resolveEndpoint(): string
    {
        return 'https://forge.laravel.com/api/servers';
    }
}
```

--------------------------------

### Execute Authorization Code Flow

Source: https://docs.saloon.dev/digging-deeper/oauth2-authentication/oauth2-authentication.md

Demonstrates the sequence of steps for the Authorization Code flow, from generating the URL to refreshing tokens.

```php
$connector = new SpotifyConnector;

// 1. Redirect the user to the authorization URL...

$authorizationUrl = $connector->getAuthorizationUrl($scopes, $state);

// 2. Handle the callback from the API provider and create an access token...

$authenticator = $connector->getAccessToken($code, $state);

// 3. Authenticate the connector

$connector->authenticate($authenticator);

// 4. Send your requests

$connector->send(new GetTracksRequest);

// 5. Refresh your access tokens...

$newAuthenticator = $connector->refreshAccessToken($authenticator);
```

--------------------------------

### Execute Client Credentials Grant Flow

Source: https://docs.saloon.dev/digging-deeper/oauth2-authentication/client-credentials-grant.md

Demonstrates the sequence of obtaining an access token and authenticating a connector.

```php
$connector = new WarehouseConnector;

// 1. Create an access token authenticator

$authenticator = $connector->getAccessToken($scopes);

// 2. Authenticate the connector

$connector->authenticate($authenticator);

// 3. Send your requests

$connector->send(new GetInventoryRequest);
```

--------------------------------

### Create a Custom Rate Limit Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Implement the RateLimitStore interface to define custom storage logic for rate limits.

```php
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;

class CustomStore implements RateLimitStore
{
    /**
     * Get a rate limit from the store
     */
    public function get(string $key): ?string
    {
        //
    }

    /**
     * Set the rate limit in the store
     */
    public function set(string $key, string $value, int $ttl): bool
    {
        //
    }
}
```

--------------------------------

### Consume the SDK resource

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Demonstrates how end-users interact with the SDK by calling the resource method on the connector instance.

```php
<?php

$pokeapi = new Pokeapi('my-api-token');

$allPokemon = $pokeapi->pokemon()->all(page: 1);

$giratina = $pokeapi->pokemon()->get(id: 'giratina');
```

--------------------------------

### Configure Memory Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Uses an in-memory array to track limits, which resets when the connector is destructed.

```php
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\MemoryStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    return new MemoryStore;
}
```

--------------------------------

### Initialize a MockClient for a specific request

Source: https://docs.saloon.dev/the-basics/testing.md

Instantiate a MockClient to intercept a specific request class and return a predefined response.

```php
use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

test('my test', function () {
    $mockClient = new MockClient([
        GetServersRequest::class => MockResponse::make(body: '', status: 200),
    ]);
    
    $connector = new ForgeConnector;
    $connector->withMockClient($mockClient);
});
```

--------------------------------

### Read and Query XML with XMLReader

Source: https://docs.saloon.dev/installable-plugins/xml-wrangler.md

Demonstrates initializing a reader from a string and performing various data extraction tasks using values, dot notation, XPath, and attribute access.

```php
use Saloon\XmlWrangler\XmlReader;

$reader = XmlReader::fromString($xml);

// Convert XML to an array

$reader->values(); // ['breakfast_menu' => [['name' => '...'], ['name' => '...'], ['name' => '...']]

// Query the XML

$reader->value('food.0')->sole(); // ['name' => 'Belgian Waffles', 'price' => '$5.95', ...]

$reader->xpathValue('//food[@bestSeller="true"]/name')->get(); // ['Belgian Waffles', 'Berry-Berry Belgian Waffles']

$reader->element('food.0')->sole()->getAttributes(); // ['soldOut' => false, 'bestSeller' => true]
```

--------------------------------

### Implement boot method in Saloon

Source: https://docs.saloon.dev/digging-deeper/middleware.md

Use the boot method to modify the PendingRequest instance. Changes made in a connector apply to all requests, while changes in a request apply only to that specific request.

```php
<?php

use Saloon\Http\Connector;
use Saloon\Http\PendingRequest;

class ForgeConnector extends Connector
{
    // ...
    
    public function boot(PendingRequest $pendingRequest): void
    {
        $pendingRequest->headers()->add('X-Current-Time', new DateTime);
    }
}
```

```php
<?php

use Saloon\Http\Request;
use Saloon\Http\PendingRequest;

class GetServersRequest extends Request
{
    // ...
    
    public function boot(PendingRequest $pendingRequest): void
    {
        $pendingRequest->headers()->add('X-Current-Time', new DateTime);
    }
}
```

--------------------------------

### Test Request Plugins

Source: https://docs.saloon.dev/installable-plugins/lawman.md

Verify pagination, caching, and rate limiting configurations on a request.

```php
test('request')
    ->expect('App\Http\Integrations\Integration\Requests\Request')
    ->toBeSaloonRequest()
    ->toSendPostRequest()
    ->toUsePagedPagination()
    ->toHaveCaching()
    ->toHaveRateLimits()
```

--------------------------------

### Implement Invokable Response Middleware

Source: https://docs.saloon.dev/digging-deeper/middleware.md

Create reusable middleware by implementing the ResponseMiddleware contract.

```php
<?php

use Saloon\Http\Response;
use Saloon\Contracts\ResponseMiddleware;

class LogResponse implements ResponseMiddleware
{
    public function __invoke(Response $response): void
    {
        Logger::recordResponse($response);
    }
}
```

```php
<?php

use Saloon\Http\PendingRequest;

$forge = new ForgeConnector;
$forge->middleware()->onResponse(new LogResponse);
```

```php
<?php

use Saloon\Http\PendingRequest;

$request = new GetServersRequest;
$request->middleware()->onResponse(new LogResponse);
```

--------------------------------

### Generate SDK from API Specification

Source: https://docs.saloon.dev/installable-plugins/sdk-generator.md

Execute the generator command to create an SDK from a JSON or YAML specification file.

```sh
sdkgenerator generate:sdk API_SPEC_FILE.{json|yaml|yml}
     --type={postman|openapi} 
     [--name=SDK_NAME] 
     [--output=OUTPUT_PATH] 
     [--namespace=Company\\Integration] 
     [--force] 
     [--dry] 
     [--zip]
```

--------------------------------

### Available Limit Intervals

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Demonstrates various time-based interval methods available on the Limit class.

```php
use Saloon\RateLimitPlugin\Limit;

Limit::allow(60)->everySeconds(seconds: 5);
Limit::allow(60)->everyMinute();
Limit::allow(60)->untilEndOfMinute();
Limit::allow(60)->everyFiveMinutes();
Limit::allow(60)->everyThirtyMinutes();
Limit::allow(60)->everyHour();
Limit::allow(60)->untilEndOfHour();
Limit::allow(60)->everySixHours();
Limit::allow(60)->everyTwelveHours();
Limit::allow(60)->everyDay();
Limit::allow(60)->everyDayUntil('8pm');
Limit::allow(60)->untilMidnightTonight();
Limit::allow(60)->untilEndOfMonth();
```

--------------------------------

### Create a PokemonResource class

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Extends BaseResource to group related API requests, passing the connector instance to manage request execution.

```php
<?php

use Saloon\Http\BaseResource;
use Saloon\Http\Response;

class PokemonResource extends BaseResource
{
     public function all(int $page): Response
     {
         return $this->connector->send(new GetAllPokemon($page));
     }
     
     public function get(int $id): Response
     {
         return $this->connector->send(new GetSinglePokemon($id));
     }
}
```

--------------------------------

### Define a basic Connector

Source: https://docs.saloon.dev/the-basics/connectors.md

Create a new connector class by extending the abstract Connector class and implementing the resolveBaseUrl method.

```php
<?php

use Saloon\Http\Connector;

class ForgeConnector extends Connector
{
    public function resolveBaseUrl(): string
    {
        return 'https://forge.laravel.com/api/v1';
    }
}
```

--------------------------------

### Implement Required Rate Limit Methods

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Define the resolveLimits and resolveRateLimitStore methods to specify how limits are tracked and stored.

```php
use Saloon\Http\Connector;
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\MemoryStore;
use Saloon\RateLimitPlugin\Traits\HasRateLimits;

class SpotifyConnector extends Connector
{
    use HasRateLimits;
    
    protected function resolveLimits(): array
    {
        return [];
    }

    protected function resolveRateLimitStore(): RateLimitStore
    {
        return new MemoryStore;
    }
}
```

--------------------------------

### Mock Requests with Saloon Facade

Source: https://docs.saloon.dev/installable-plugins/laravel-integration.md

Use the Saloon facade in tests to mock requests instead of the global MockClient.

```php
use Saloon\Laravel\Facades\Saloon;

Saloon::fake([
    GetServersRequest::class => MockResponse::make(body: '', status: 200),
]);
```

--------------------------------

### Implement Basic Authentication

Source: https://docs.saloon.dev/the-basics/authentication.md

Uses the BasicAuthenticator class to add an Authorization: Basic header to requests.

```php
<?php

use Saloon\Http\Auth\BasicAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(
        public readonly string $username,
        public readonly string $password
    ){}
    
    protected function defaultAuth(): BasicAuthenticator
    {
        return new BasicAuthenticator($this->username, $this->password);
    }
}
```

--------------------------------

### Executing requests with user-provided handles

Source: https://docs.saloon.dev/upgrade/upgrading-from-v3-to-v4.md

Demonstration of normal operation versus a potential attack vector using user-provided handles.

```php
$form = [
   'handle' => '@saloon',
];

new InstagramConnector()->send(new GetProfileRequest($form['handle']))
```

```php
$form = [
   'handle' => 'https://some-attacker-server.tld/attack',
];

new InstagramConnector()->send(new GetProfileRequest($form['handle']))
```

--------------------------------

### Configure HTTP client options

Source: https://docs.saloon.dev/the-basics/connectors.md

Override the defaultConfig method or use the config method on an instance to pass options to the underlying Guzzle client.

```php
class ForgeConnector extends Connector
{
    // ...

    public function defaultConfig(): array
    {
        return [
            'stream' => true,
        ];
    }
}
```

```php
$forge = new ForgeConnector;

$forge->config()->add('stream', true);
```

--------------------------------

### Configure Predis Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Connects to Redis using the predis/predis library.

```php
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\PredisStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    $client = new Predis\Client([
        'scheme' => 'tcp',
        'host'   => '10.0.0.1',
        'port'   => 6379,
    ]);

    return new PredisStore($client);
}
```

--------------------------------

### Configure File Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Persists limits to the local filesystem using a specified directory path.

```php
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\FileStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    return new FileStore('some/application/directory');
}
```

--------------------------------

### Send Requests via SDK

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Execute requests by instantiating a request class and passing it to the connector's send method.

```php
<?php

use Pokeapi\Pokeapi;

$pokeapi = new Pokeapi('my-api-token');
$request = new GetAllPokemon(page: 1);

// Developers would just send the request.

$response = $pokeapi->send($request);
```

--------------------------------

### Configure Rate Limits in a Connector

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Implement the HasRateLimits trait and define limits and storage in a connector class.

```php
<?php

use Saloon\Http\Connector;
use Saloon\RateLimitPlugin\Limit;
use Saloon\Traits\Plugins\AcceptsJson;
use Saloon\RateLimitPlugin\Stores\RedisStore;
use Saloon\RateLimitPlugin\Traits\HasRateLimits;
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;

class SpotifyConnector extends Connector
{
    use AcceptsJson;
    use HasRateLimits;

    public function resolveBaseUrl(): string
    {
        return 'https://api.spotify.com/v1';
    }

    protected function resolveLimits(): array
    {
        return [
            Limit::allow(100)->everyMinute(),
            Limit::allow(1000)->everyDay(),
            Limit::allow(5000)->everyMonth(),
        ];
    }

    protected function resolveRateLimitStore(): RateLimitStore
    {
        $redis = new Redis;
        $redis->connect('127.0.0.1');
    
        return new RedisStore($redis);
    }
}
```

--------------------------------

### Test Saloon Connectors

Source: https://docs.saloon.dev/installable-plugins/lawman.md

Compare standard PestPHP expectations with Lawman's simplified syntax for testing connector traits.

```php
test('connector')
    ->expect('App\Http\Integrations\Integration\Connector')
    ->toExtend('Saloon\Http\Connector')
    ->toUse('Saloon\Traits\Plugins\AcceptsJson')
    ->toUse('Saloon\Traits\Plugins\AlwaysThrowOnErrors');
```

```php
test('connector')
    ->expect('App\Http\Integrations\Integration\Connector')
    ->toBeSaloonConnector()
    ->toUseAcceptsJsonTrait()
    ->toUseAlwaysThrowOnErrorsTrait();
```

--------------------------------

### Configure Paginator Properties and Methods

Source: https://docs.saloon.dev/installable-plugins/pagination/limit-offset-pagination.md

Define the perPageLimit property and implement isLastPage and getPageItems methods to control pagination logic.

```php
<?php

use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\OffsetPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;

class SpotifyConnector extends Connector implements HasPagination
{
    // ...
    
    public function paginate(Request $request): OffsetPaginator
    {
        return new class(connector: $this, request: $request) extends OffsetPaginator
        {
            protected ?int $perPageLimit = 100;
        
            protected function isLastPage(Response $response): bool
            {
                return $this->getOffset() >= (int)$response->json('total');
            }
            
            protected function getPageItems(Response $response, Request $request): array
            {
                return $response->json('items');
            }
        };
    }
}
```

--------------------------------

### Comparing Synchronous and Concurrent Requests

Source: https://docs.saloon.dev/digging-deeper/concurrency-and-pools.md

Demonstrates the performance difference between standard synchronous loops and using a generator with the pool method.

```php
<?php

$connector = new TestConnector;

// ⬇️ Takes 60 seconds... 😪

$requests = function () {
    for ($i = 0; $i < 1000; $i++) {
        $connector->send(new GetUserRequest);
    }
};

// ⬇️ Takes 2.5 seconds! 🔥

$requests = function () {
    for ($i = 0; $i < 1000; $i++) {
        yield new GetUserRequest;
    }
};

$connector->pool($requests, concurrency: 10)->send()->wait();
```

--------------------------------

### Define an SDK Connector

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Create a base connector class extending Saloon's Connector to define the API base URL, default headers, and authentication.

```php
<?php

namespace Pokeapi;

use Saloon\Http\Request;
use Saloon\Http\Connector;
use Saloon\Http\Auth\TokenAuthenticator;

class Pokeapi extends Connector
{
    public function __construct(protected readonly string $token) {}

    public function resolveBaseUrl(): string
    {
        return 'https://pokeapi.co/api/v2';
    }

    protected function defaultHeaders(): array
    {
        return [
            'Accept' => 'application/json',
            'Content-Type' => 'application/json',
        ];
    }
    
    protected function defaultAuth(): TokenAuthenticator
    {
        return new TokenAuthenticator($this->token);
    }
}
```

--------------------------------

### Define a Saloon Plugin Trait

Source: https://docs.saloon.dev/installable-plugins/building-your-own-plugins.md

Create a trait with a method prefixed with 'boot' followed by the trait name to hook into the request lifecycle.

```php
<?php

trait HasLogging
{
    public function bootHasLogging(PendingRequest $pendingRequest): void
    {
        ray($pendingRequest);
    }
}
```

--------------------------------

### Use constructor arguments for dynamic properties

Source: https://docs.saloon.dev/the-basics/connectors.md

Define a constructor to pass dynamic values like base URLs during connector instantiation.

```php
class ForgeConnector extends Connector
{
    public function __construct(protected readonly string $baseUrl) {
        //
    }

    public function resolveBaseUrl(): string
    {
        return $this->baseUrl;
    }
}
```

```php
$connector = new ForgeConnector('https://forge.laravel.com/api/v1');
```

--------------------------------

### Register Global Middleware

Source: https://docs.saloon.dev/digging-deeper/middleware.md

Apply middleware globally using the Config class, ensuring unique naming to prevent duplicate registration.

```php
<?php

use Saloon\Config;

Config::globalMiddleware()->onResponse(new LogResponse, 'logResponse');
```

--------------------------------

### Configure query parameters

Source: https://docs.saloon.dev/the-basics/requests.md

Define default query parameters in the request class or add them dynamically to a request instance.

```php
class GetServersRequest extends Request
{
    // ...
    
    protected function defaultQuery(): array
    {
        return [
            'sort' => 'name', // ?sort=name
            'filter[active]' => 'true', // ?filter[active]=true
        ];
    }
}
```

```php
$request = new GetServersRequest;

$request->query()->add('sort', 'provider');
```

--------------------------------

### Populate default body using an array

Source: https://docs.saloon.dev/the-basics/request-body-data/json-body.md

Accept an array in the constructor to dynamically populate the request body.

```php
<?php

use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasJsonBody;

class CreateServerRequest extends Request implements HasBody
{
    use HasJsonBody;

    protected Method $method = Method::POST;
    
    public function __construct(
        protected array $payload
    ){}
    
    protected function defaultBody(): array
    {
        return $this->payload;
    }
}
```

--------------------------------

### Mock requests using URL patterns

Source: https://docs.saloon.dev/the-basics/testing.md

Define mock responses based on specific URL strings or use wildcards to match multiple endpoints.

```php
$mockClient = new MockClient([
    'forge.laravel.com/api/v1/servers' => MockResponse::make(body: '', status: 200),
    'forge.laravel.com/*' => MockResponse::make(body: '', status: 200),
]);
```

--------------------------------

### Define and Use Connector Methods

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Add helper methods to the connector class to wrap request execution, providing a cleaner API for the end user.

```php
class Pokeapi extends Connector
{
    // ...
    
    public function allPokemon(int $page): Response
    {
        return $this->send(new GetAllPokemon($page));
    }
}
```

```php
<?php

$pokeapi = new Pokeapi('my-api-token');

$response = $pokeapi->allPokemon(page: 1);
```

--------------------------------

### Implement Query Parameter Authentication

Source: https://docs.saloon.dev/the-basics/authentication.md

Uses the QueryAuthenticator class to include an authentication token as a query parameter.

```php
<?php

use Saloon\Http\Auth\QueryAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(public readonly string $token) {}
    
    protected function defaultAuth(): QueryAuthenticator
    {
        return new QueryAuthenticator('api-key', $this->token);
    }
}
```

--------------------------------

### Execute On-the-fly Retries with sendAndRetry

Source: https://docs.saloon.dev/digging-deeper/retrying-requests.md

Use the sendAndRetry method for ad-hoc retry configuration without modifying the connector class.

```php
<?php

$forgeConnector = new ForgeConnector;

$response = $forgeConnector->sendAndRetry(
    request: new UnreliableRequest,
    tries: 3,
    interval: 500,
    handleRetry: function (FatalRequestException|RequestException $exception, Request $request) {
        //
    },
    throw: true,
    useExponentialBackoff: true,
);
```

--------------------------------

### Implement Invokable Middleware Classes

Source: https://docs.saloon.dev/digging-deeper/middleware.md

Define reusable middleware by implementing the RequestMiddleware interface and using the class instance with the onRequest method.

```php
<?php

use Saloon\Http\PendingRequest;
use Saloon\Contracts\RequestMiddleware;

class AuthenticateRequest implements RequestMiddleware
{
    public function __invoke(PendingRequest $pendingRequest): void
    {
        $pendingRequest->headers()->add('Authorization', 'Bearer ' . $token);
    }
}
```

```php
<?php

use Saloon\Http\PendingRequest;

$forge = new ForgeConnector;
$forge->middleware()->onRequest(new AuthenticateRequest);
```

```php
<?php

use Saloon\Http\PendingRequest;

$request = new GetServersRequest;
$request->middleware()->onRequest(new AuthenticateRequest);
```

--------------------------------

### Implement HasPagination interface

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Add the HasPagination interface to your connector and define the required paginate method.

```php
<?php

use Saloon\Http\Connector;
use Saloon\PaginationPlugin\Paginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;

class SpotifyConnector extends Connector implements HasPagination
{
    // ...
    
    public function paginate(Request $request): Paginator
    {
        //
    }
}
```

--------------------------------

### Implement pagination logic methods

Source: https://docs.saloon.dev/installable-plugins/pagination/custom-pagination.md

Define isLastPage, getPageItems, and applyPagination methods to handle API-specific pagination requirements.

```php
<?php

use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\Paginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;

class SpotifyConnector extends Connector implements HasPagination
{
    // ...

    public function paginate(Request $request): Paginator
    {
        return new class(connector: $this, request: $request) extends Paginator
        {
            protected function isLastPage(Response $response): bool
            {
                return is_null($response->json('next_page_url'));
            }

            protected function getPageItems(Response $response, Request $request): array
            {
                return $response->json('items');
            }

            protected function applyPagination(Request $request): Request
            {
                $request->headers()->add('X-Page', $this->currentPage);

                $request->headers()->add('X-Per-Page', $this->perPageLimit);

                return $request;
            }
        };
    }
}
```

--------------------------------

### Configure Redis Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Utilizes the PHP Redis extension to store limits in a Redis database.

```php
use Redis;
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\RedisStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    $client = new Redis;
    $client->connect('127.0.0.1');

    return new RedisStore($client);
}
```

--------------------------------

### Send a synchronous request

Source: https://docs.saloon.dev/the-basics/sending-requests.md

Instantiate a connector and a request class, then pass the request to the connector's send method.

```php
<?php

$forge = new ForgeConnector;
$request = new GetServersRequest;

$response = $forge->send($request);
```

--------------------------------

### Configure request headers

Source: https://docs.saloon.dev/the-basics/requests.md

Define default headers within the request class or add them dynamically to a request instance.

```php
class GetServersRequest extends Request
{
    // ...

    protected function defaultHeaders(): array
    {
        return [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ];
    }
}
```

```php
$request = new GetServersRequest;

$request->headers()->add('Content-Type', 'text/plain');
```

--------------------------------

### Update Config and MockConfig Namespaces

Source: https://docs.saloon.dev/upgrade/upgrading-from-v2-to-v3.md

Update use statements to reflect the move of Config and MockConfig classes to the root Saloon namespace.

```php
use Saloon\Helpers\Config
use Saloon\Config
```

```php
use Saloon\Helpers\MockConfig
use Saloon\MockConfig
```

--------------------------------

### Implement updated Sender interface

Source: https://docs.saloon.dev/upgrade/upgrading-from-v2-to-v3.md

Custom senders must now implement getFactoryCollection, send, and sendAsync methods.

```php
<?php

interface Sender
{
    /**
     * Get the factory collection
     */
    public function getFactoryCollection(): FactoryCollection;

    /**
     * Send the request synchronously
     */
    public function send(PendingRequest $pendingRequest): Response;

    /**
     * Send the request asynchronously
     */
    public function sendAsync(PendingRequest $pendingRequest): PromiseInterface;
}
```

--------------------------------

### Instantiate request-level paginator

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Pass the connector into the request's paginate method to retrieve the paginator instance.

```php
<?php

$spotifyConnector = new SpotifyConnector;
$request = new GetLikedSongsRequest;

$paginator = $request->paginate($spotifyConnector);
```

--------------------------------

### Define a resource method on the connector

Source: https://docs.saloon.dev/digging-deeper/building-sdks.md

Exposes the resource class through a method on the main connector class for easy access.

```php
class Pokeapi extends Connector
{
    // ...
    
    public function pokemon(): PokemonResource
    {
        return new PokemonResource($this);
    }
}
```

--------------------------------

### Use Saloon Laravel Facade for Mocking

Source: https://docs.saloon.dev/the-basics/testing.md

Utilize the Saloon facade as an alias for global mocking when using the official Laravel plugin.

```php
use Saloon\\\Laravel\\\Facades\\\Saloon;

Saloon::fake([
    GetServersRequest::class => MockResponse::make(body: '', status: 200),
]);
```

--------------------------------

### Customize fixture storage location

Source: https://docs.saloon.dev/the-basics/testing.md

Sets a custom directory path for storing fixture files.

```php
MockConfig::setFixturePath('tests/other-directory');
```

--------------------------------

### Configure JSON encoding flags

Source: https://docs.saloon.dev/the-basics/request-body-data/json-body.md

Demonstrates using setJsonFlags within a constructor to customize how the JSON body is encoded.

```php
<?php

use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasJsonBody;

class CreateServerRequest extends Request implements HasBody
{
    use HasJsonBody;
    
    public function __construct()
    {
        $this->body()->setJsonFlags(JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
    }
}
```

--------------------------------

### Test Saloon Requests

Source: https://docs.saloon.dev/installable-plugins/lawman.md

Compare standard PestPHP expectations with Lawman's simplified syntax for testing request implementations and traits.

```php
test('request')
    ->expect('App\Http\Integrations\Integration\Requests\Request')
    ->toExtend('\Saloon\Http\Request')
    ->toImplement('Saloon\Contracts\Body\HasBody')
    ->toUse('Saloon\Traits\Body\HasFormBody')
    ->toUse('Saloon\Traits\Plugins\AcceptsJson');
```

```php
test('request')
    ->expect('App\Http\Integrations\Integration\Requests\Request')
    ->toBeSaloonRequest()
    ->toSendPostRequest()
    ->toHaveFormBody()
    ->toUseAcceptsJsonTrait();
```

--------------------------------

### Using the Refactored Connector

Source: https://docs.saloon.dev/conclusion/how-to-guides/per-request-authentication.md

Simplified usage of the API after implementing the automated authentication logic in the connector.

```php
<?php

$api = new MusicApi(
    username: 'Sam',
    password: 'yee-haw',
);

$response = $api->send(new GetSongsByArtistRequest('Luke Combs'));

// 200 body: [{name: 'When it rains, it pours'}]
```

--------------------------------

### Define manual mock responses with JSON

Source: https://docs.saloon.dev/the-basics/testing.md

Use MockResponse::make to manually define body content, status codes, and headers. Arrays passed as the body are automatically converted to JSON.

```php
$mockClient = new MockClient([
    GetUserRequest::class => MockResponse::make(
        body: ['user' => ['name' => 'Sam']], 
        status: 200, 
        headers: ['Content-Type' => 'application/json']
    ),
]);
```

--------------------------------

### Iterating Over Responses

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Use a foreach loop to access each page as a Saloon Response object, keeping memory usage low by loading one page at a time.

```php
<?php

$spotifyConnector = new SpotifyConnector;

$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);

foreach($paginator as $response) {
    $status = $response->status();
    $data = $response->body();
}
```

--------------------------------

### Provide requests as an array

Source: https://docs.saloon.dev/digging-deeper/concurrency-and-pools.md

Pass an array of request instances directly to the pool method or via setRequests.

```php
<?php

$forge = new ForgeConnector;

$forge->pool([
    new GetServersRequest,
    new GetSitesRequest,
    new GetUserRequest,
]);

// Or 

$pool = $forge->pool();

$pool->setRequests([
    new GetServersRequest,
    new GetSitesRequest,
    new GetUserRequest,
]);
```

--------------------------------

### Enable Asynchronous Pagination

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Call the async() method on the paginator to iterate through results as Promises.

```php
<?php

$spotifyConnector = new SpotifyConnector;

$paginator = $spotifyConnector->paginate(new GetLikedSongsRequest);

$paginator->async();

foreach($paginator as $promise) {
    // $promise->then()
}
```

--------------------------------

### Implement Paginator Methods

Source: https://docs.saloon.dev/installable-plugins/pagination/cursor-pagination.md

Define the getNextCursor, isLastPage, and getPageItems methods to control the pagination flow and data extraction.

```php
<?php

use Saloon\Http\Response;
use Saloon\Http\Connector;
use Saloon\PaginationPlugin\CursorPaginator;
use Saloon\PaginationPlugin\Contracts\HasPagination;

class SpotifyConnector extends Connector implements HasPagination
{
    // ...
    
    public function paginate(Request $request): CursorPaginator
    {
        return new class(connector: $this, request: $request) extends CursorPaginator
        {
            protected function getNextCursor(Response $response): int|string
            {
                return $response->json('next_cursor');
            }
        
            protected function isLastPage(Response $response): bool
            {
                return is_null($response->json('next_cursor'));
            }
            
            protected function getPageItems(Response $response, Request $request): array
            {
                return $response->json('items');
            }
        };
    }
}
```

--------------------------------

### Configure PSR Cache Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Supports any PSR-16 compliant cache store.

```php
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\PsrStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    return new PsrStore(new SomePsr16Store);
}
```

--------------------------------

### Implement Certificate Authentication

Source: https://docs.saloon.dev/the-basics/authentication.md

Uses the CertificateAuthenticator class for client-side certificate authentication.

```php
<?php

use Saloon\Http\Auth\CertificateAuthenticator;

class ForgeConnector extends Connector
{
    public function __construct(
        public readonly string $path,
        public readonly string $password
    ){}
    
    protected function defaultAuth(): CertificateAuthenticator
    {
        return new CertificateAuthenticator($this->path, $this->password);
    }
}
```

--------------------------------

### Configure Laravel Cache Store

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Uses Laravel's cache system to store rate limits.

```php
use Illuminate\Support\Facades\Cache;
use Saloon\RateLimitPlugin\Contracts\RateLimitStore;
use Saloon\RateLimitPlugin\Stores\LaravelCacheStore;

protected function resolveRateLimitStore(): RateLimitStore
{
    return new LaravelCacheStore(Cache::store('redis'));
}
```

--------------------------------

### Configure Global Mock Client Cleanup

Source: https://docs.saloon.dev/the-basics/testing.md

Ensures the global mock client is destroyed before each test to prevent state leakage between tests.

```php
use Saloon\Http\Faking\MockClient;

uses()
    ->beforeEach(fn () => MockClient::destroyGlobal())
    ->in(__DIR__);
```

```php
use Saloon\Http\Faking\MockClient;

class RequestTest extends TestCase
{
    protected function setUp(): void
    {
        MockClient::destroyGlobal();
    }
}
```

--------------------------------

### Handle RateLimitReachedException with Try/Catch

Source: https://docs.saloon.dev/installable-plugins/handling-rate-limits.md

Catch rate limit exceptions to retrieve the remaining wait time and handle the error gracefully.

```php
use Saloon\RateLimitPlugin\Exceptions\RateLimitReachedException;

$spotify = new SpotifyConnector;

try {
   $response = $spotify->send(new GetPlaylistRequest);
} catch (RateLimitReachedException $exception) {
    $seconds = $exception->getLimit()->getRemainingSeconds();
    
    // Return our users back to our application with a custom response that could be 
    // shown on the front end.

    return response("Too many requests to Spotify's API. Please try again in ${$seconds} seconds.");
}
```

--------------------------------

### Return a sequence of responses

Source: https://docs.saloon.dev/the-basics/testing.md

Provide an array of responses to be returned in order, regardless of the specific API call made.

```php
$mockClient = new MockClient([
    MockResponse::make(body: 'First', status: 200),
    MockResponse::make(body: 'Second', status: 200),
    MockResponse::make(body: 'Third', status: 200),
]);
```

--------------------------------

### Send a SoloRequest

Source: https://docs.saloon.dev/digging-deeper/solo-requests.md

Execute the request directly by calling the send or sendAsync methods on the request instance.

```php
<?php

$request = new GetAllPokemonRequest;
$response = $request->send();
```

--------------------------------

### Configure default headers

Source: https://docs.saloon.dev/the-basics/connectors.md

Define common headers for all requests using the defaultHeaders method or add them dynamically on a connector instance.

```php
class ForgeConnector extends Connector
{
    // ...

    protected function defaultHeaders(): array
    {
        return [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ];
    }
}
```

```php
$forge = new ForgeConnector;

$forge->headers()->add('Content-Type', 'text/plain');
```

--------------------------------

### Iterate through paginated results

Source: https://docs.saloon.dev/installable-plugins/pagination.md

Demonstrates using the paginate method on a connector to iterate through items across multiple pages.

```php
<?php

$spotifyConnector = new SpotifyConnector;

$likedSongs = $spotifyConnector->paginate(new GetLikedSongsRequest);

foreach($likedSongs->items() as $likedSong) {
    // e.g. Luke Combs - When It Rains It Pours 🎵
}
```

--------------------------------

### Define a basic Saloon request class

Source: https://docs.saloon.dev/the-basics/requests.md

Create a request class by extending the Request abstract class and defining the HTTP method and endpoint.

```php
<?php

use Saloon\Enums\Method;
use Saloon\Http\Request;

class GetServersRequest extends Request
{
    protected Method $method = Method::GET;

    public function resolveEndpoint(): string
    {
        return '/servers';
    }
}
```

--------------------------------

### Apply Authenticator at Runtime

Source: https://docs.saloon.dev/the-basics/authentication.md

Uses the authenticate method on a connector instance to set or override authentication dynamically.

```php
$forge = new ForgeConnector;

$forge->authenticate(new TokenAuthenticator($user->forge_token));

// $forge->send(...)
```

--------------------------------

### Customize Authenticator Creation

Source: https://docs.saloon.dev/digging-deeper/oauth2-authentication/client-credentials-grant.md

Extends the connector to return a custom authenticator class.

```php
<?php

protected function createOAuthAuthenticator(string $accessToken, ?DateTimeImmutable $expiresAt = null): OAuthAuthenticatorInterface
{
    return new WarehouseAuthenticator($accessToken, $expiresAt);
}
```

--------------------------------

### Test Connector Retry Logic

Source: https://docs.saloon.dev/installable-plugins/lawman.md

Verify retry instructions and backoff strategies on a connector.

```php
test('connector')
    ->expect('App\Http\Integrations\Integration\Connector')
    ->toBeSaloonConnector()
    ->toBeTriedAgainOnFailure()
    ->toHaveRetryInterval()
    ->toUseExponentialBackoff()
```

--------------------------------

### Test requests with a local MockClient

Source: https://docs.saloon.dev/the-basics/testing.md

Uses the withMockClient method to inject a local mock client into a connector for isolated testing.

```php
<?php

test('a request sends the correct body', function () {
    $mockClient = new MockClient([
        CreateServerRequest::class => MockResponse::make('Server Created', 200),
    ]);

    $connector = new ForgeConnector;
    $connector->withMockClient($mockClient);
    
    $connector->send(new CreateServerRequest($name, $ip));
    
    $mockClient->assertSent(function (Request $request) {
        return $request->body()->all() === ['name' => $name, 'ip' => $ip];
    });
});
```

--------------------------------

### Defining a Default Body with Constructor Arguments

Source: https://docs.saloon.dev/the-basics/request-body-data/string-plain-text-body.md

Use the defaultBody method to standardize request bodies using constructor arguments.

```php
<?php

use Saloon\Http\Request;
use Saloon\Contracts\Body\HasBody;
use Saloon\Traits\Body\HasStringBody;

class CreateServerRequest extends Request implements HasBody
{
    use HasStringBody;

    protected Method $method = Method::POST;
    
    public function __construct(
        protected string $ubuntuVersion,
        protected string $provider
    ){}
    
    protected function defaultBody(): string
    {
        return 'Howdy, Partner. I want a ' . $this->ubuntuVersion . ' server through ' . $this->provider . ' provider!';
    }
}
```
Tokens:
Raw