Saloon

https://github.com/saloonphp/saloon
Admin
Saloon is a PHP package that helps you build beautiful API integrations and SDKs with reusable...
Tokens:133,186
Snippets:1,058
Trust Score:8.9
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### GetServerStatusRequest example using SoloRequest

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/request.md

Shows a concrete SoloRequest subclass that sends a GET request to an absolute endpoint with token authentication. The request is sent directly via send() without a connector, leveraging the default NullConnector.

```php
<?php

use Saloon\Http\SoloRequest;
use Saloon\Enums\Method;
use Saloon\Http\Auth\TokenAuthenticator;

class GetServerStatusRequest extends SoloRequest
{
    protected Method $method = Method::GET;

    public function resolveEndpoint(): string
    {
        return 'https://status.example.com/api';
    }

    protected function defaultAuth(): ?\Saloon\Contracts\Authenticator
    {
        return new TokenAuthenticator($this->token);
    }
}

$response = (new GetServerStatusRequest)->send();

```

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

### Example Request subclass and error handling for missing method

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/request.md

Shows a working GetServersRequest with a method property and a BrokenRequest that omits it, catching the LogicException from getMethod().

```php
<?php

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

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

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

// Error handling: forgetting the method property
class BrokenRequest extends Request
{
    public function resolveEndpoint(): string
    {
        return '/broken';
    }
}

try {
    (new BrokenRequest)->getMethod();
} catch (\LogicException $e) {
    echo $e->getMessage(); // 'Your request is missing a HTTP method. ...'
}
```

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

### UserResource example extending BaseResource

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/request.md

Shows a concrete resource class that extends BaseResource and uses the injected connector to send a GetUsersRequest. The all() method returns a Response from the connector's send() method.

```php
<?php

use Saloon\Http\BaseResource;

class UserResource extends BaseResource
{
    public function all(): \Saloon\Http\Response
    {
        return $this->connector->send(new GetUsersRequest);
    }
}

```

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

### Conditionable usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-utility.md

Conditionally applies a mock client when the app environment is staging.

```php
$connector->when(config('app.env') === 'staging', fn ($c) => $c->withMockClient($mockClient));
```

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

### Example request classes using body traits

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Shows CreateUserRequest using HasJsonBody and GraphQLRequest using HasXmlBody. Forgetting implements HasBody surfaces as BodyException.

```php
<?php

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

class CreateUserRequest extends Request implements HasBody
{
    use HasJsonBody;

    protected Method $method = Method::POST;

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

    protected function defaultBody(): array
    {
        return ['name' => 'Sam', 'role' => 'admin'];
    }
}

// Runtime mutation before sending
$request = new CreateUserRequest;
$request->body()->add('active', true);

// Keep a string body for raw payloads (XML, GraphQL, ...)
class GraphQLRequest extends Request implements HasBody
{
    use HasXmlBody;

    protected Method $method = Method::POST;
    public function resolveEndpoint(): string { return '/graphql'; }
    protected function defaultBody(): ?string { return '<query>...</query>'; }
}
```

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

### HasApiVersion usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Example connector using HasApiVersion with VersionMode::QueryParam and versionKey 'v'. After setApiVersion('2026-01'), every request carries ?v=2026-01.

```php
<?php

use Saloon\Traits\Plugins\HasApiVersion;
use Saloon\Enums\VersionMode;

class VersionedConnector extends \Saloon\Http\Connector
{
    use HasApiVersion;

    protected VersionMode $versionMode = VersionMode::QueryParam;
    protected string $versionKey = 'v';

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

$connector = (new VersionedConnector)->setApiVersion('2026-01');
// every request now carries ?v=2026-01
```

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

### OAuthConfig usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/oauth2.md

Builds an OAuthConfig with client credentials, redirect URI, scopes, and custom endpoints, then validates it. The try/catch handles missing client id/secret/redirect uri.

```php
<?php

use Saloon\Helpers\OAuth2\OAuthConfig;

$config = OAuthConfig::make()
    ->setClientId('client-id')
    ->setClientSecret('secret')
    ->setRedirectUri('https://app.example.com/callback')
    ->setDefaultScopes(['read', 'write'])
    ->setAuthorizeEndpoint('oauth/authorize')
    ->setTokenEndpoint('oauth/token')
    ->setUserEndpoint('oauth/me');

try {
    $config->validate();
} catch (\Saloon\Exceptions\OAuthConfigValidationException $e) {
    // missing client id/secret/redirect uri
}
```

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

### Typical Connector usage with ForgeConnector

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/connector.md

Example of subclassing Connector with constructor credentials, resolveBaseUrl(), defaultHeaders(), and defaultAuth(). Shows sending a request with an anonymous Request class.

```php
<?php

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

class ForgeConnector extends Connector
{
    public function __construct(protected string $apiToken) {}

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

    public function defaultHeaders(): array
    {
        return ['Accept' => 'application/json'];
    }

    public function defaultAuth(): ?\Saloon\Contracts\Authenticator
    {
        return new \Saloon\Http\Auth\TokenAuthenticator($this->apiToken);
    }
}

$connector = new ForgeConnector('token');
$response = $connector->send(new class extends Request {
    protected Method $method = Method::GET;
    public function resolveEndpoint(): string { return '/servers'; }
});
```

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

### Register middleware for request, response, and fatal exceptions

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/middleware-pipeline.md

Shows how to attach middleware to the connector's pipeline. onRequest runs before every request, onResponse after every response (including fakes), and onFatalException on network failure when no response existed. The onResponse example uses PipeOrder::LAST.

```php
<?php

$connector->middleware()->onRequest(function (\Saloon\Http\PendingRequest $pendingRequest) {
    // runs before every request
}, name: 'logRequest');

$connector->middleware()->onResponse(function (\Saloon\Http\Response $response) {
    // runs after every response (including fakes)
}, name: 'logResponse', order: \Saloon\Enums\PipeOrder::LAST);

$connector->middleware()->onFatalException(function (\Saloon\Exceptions\Request\FatalRequestException $e) {
    // network failure — no response existed
});
```

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

### Response failure handling usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/response.md

Shows chained non-throwing inspection with failed() and json(), plus a throwing variant with typed catch for NotFoundException and generic RequestException.

```php
<?php

use Saloon\Exceptions\Request\Statuses\NotFoundException;

$response = $connector->send(new GetServerRequest);

// Chained, non-throwing inspection
$name = $response->failed() ? null : $response->json('data.name');

// Throwing variant with typed catch
try {
    $response->throw()->dto();
} catch (NotFoundException $e) {
    // 404 specifically
} catch (\Saloon\Exceptions\Request\RequestException $e) {
    // other failed responses
}
```

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

### Example of defaultAuth() override in a Connector

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-utility.md

Shows how to override defaultAuth() in a Connector to return a TokenAuthenticator. Also notes per-request authentication via (new PublicRequest)->authenticate(new NullAuthenticator).

```php
<?php

use Saloon\Http\Auth\TokenAuthenticator;

class AuthedConnector extends \Saloon\Http\Connector
{
    protected function defaultAuth(): ?\Saloon\Contracts\Authenticator
    {
        return new TokenAuthenticator($this->apiToken);
    }

    // or per-request: (new PublicRequest)->authenticate(new NullAuthenticator)
}
```

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

### Macroable usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-utility.md

Defines a 'displayName' macro on Response that accesses the response JSON. The closure's $this is the Response instance.

```php
<?php

use Saloon\Http\Response;

Response::macro('displayName', function (): string {
    return $this->json('user.name');   // $this is the Response
});

$name = $response->displayName();
```

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

### RetryingConnector and SensitiveRequest example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-request-properties.md

Shows a connector with retry settings (tries=3, retryInterval=500, exponential backoff) and a request that overrides throwOnMaxTries to false and customizes handleRetry to skip retrying 4xx errors except 429. The handleRetry hook is called in send order: the $handleRetry argument (if provided), then request, then connector; all must return true to continue retrying.

```php
<?php

use Saloon\Http\Request;
use Saloon\Http\Connector;

class RetryingConnector extends Connector
{
    public int $tries = 3;
    public int $retryInterval = 500;
    public bool $useExponentialBackoff = true;
}

class SensitiveRequest extends Request
{
    public bool $throwOnMaxTries = false; // return last response instead of throwing

    public function handleRetry(
        \Saloon\Exceptions\Request\FatalRequestException|\Saloon\Exceptions\Request\RequestException $exception,
        Request $request
    ): bool {
        // Don't retry 4xx except 429
        if ($exception instanceof \Saloon\Exceptions\Request\RequestException && $exception->getStatus() >= 400 && $exception->getStatus() !== 429) {
            return false;
        }

        return parent::handleRetry($exception, $request);
    }
}
```

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

### Fixture::__construct

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Initializes a new Fixture instance with the given name, storage backend, and context. The fixture name can be empty and resolved later via defineName().

```APIDOC
## Fixture::__construct

### Description
Initializes a new Fixture instance with the given name, storage backend, and context.

### Method
constructor

### Signature
`public function __construct(string $name = '', ?Storage $storage = null, ?ArrayStoreContract $context = null)`

### Parameters
- **$name** (string) - Optional - Fixture name (alphanumerics, `-`, `_`, `/`, `\`); empty → resolved from `defineName()`.
- **$storage** (?Storage) - Optional - Storage backend (creates the fixture dir if missing). Defaults to `new Storage(MockConfig::getFixturePath(), true)`.
- **$context** (?ArrayStoreContract) - Optional - Context stored alongside each recording. Defaults to `new ArrayStore()`.
```

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

### SignedRequest example overriding handlePsrRequest

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-sending.md

Example of overriding handlePsrRequest in a Request subclass to add an HMAC signature header. Uses hash_hmac with SHA-256 and a secret key, then adds the X-Signature header to the request.

```php
<?php

use Psr\Http\Message\RequestInterface;
use Saloon\Http\PendingRequest;

class SignedRequest extends Request
{
    public function handlePsrRequest(RequestInterface $request, PendingRequest $pendingRequest): RequestInterface
    {
        $signature = hash_hmac('sha256', (string) $request->getUri(), 'secret');

        return $request->withHeader('X-Signature', $signature);
    }
}
```

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

### MockClient usage with request class and URL pattern

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Creates a mock client mapping a request class and a URL pattern to mock responses, sends a request without network I/O, and asserts that the request was sent with a matching response status.

```php
<?php

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

$mockClient = new MockClient([
    GetServersRequest::class => MockResponse::make(['servers' => []], 200, ['Content-Type' => 'application/json']),
    '*/users/*' => MockResponse::make(['name' => 'Sam']),
]);

$response = $connector->send(new GetServersRequest, $mockClient); // no network I/O

$mockClient->assertSent(GetServersRequest::class);
$mockClient->assertSent(function (GetServersRequest $request, $response) {
    return $response->status() === 200;
});
```

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

### GetUserRequest class definition

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/oauth2.md

Defines the built-in OAuth2 user request. Uses GET method and constructs with OAuthConfig. The endpoint is resolved from oauthConfig->getUserEndpoint() and there is no defaultBody because it is a GET request.

```php
protected Method $method = Method::GET;
public function __construct(protected OAuthConfig $oauthConfig)
public function resolveEndpoint(): string      // oauthConfig->getUserEndpoint()
// no defaultBody() — GET request
```

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

### RecordedResponse snapshot usage

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Shows how to capture a response into a RecordedResponse, convert it to a file, and restore it as a mock response body. fromResponse captures status, headers, and body; toFile produces pretty JSON with base64 for binary data.

```php
$recorded = RecordedResponse::fromResponse($response); // captures status/headers/body
$jsonFileContents = $recorded->toFile();               // pretty JSON (+ base64 for binary)
$servedAgain = RecordedResponse::fromFile($contents)->toMockResponse()->body();
```

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

### ManagesPsrRequests trait definition

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-sending.md

Trait used by PendingRequest only. Provides methods to get the URI, create a PSR-7 request, and get the factory collection. createUri parses existing query and merges with query()->all(). createPsrRequest applies headers (null → ''), attaches body stream, then calls connector->handlePsrRequest() and request->handlePsrRequest().

```php
trait ManagesPsrRequests
{
    protected FactoryCollection $factoryCollection;

    public function getUri(): UriInterface
    // createUri(url) → parse existing query → withQuery(http_build_query(existing + query()->all()))

    public function createPsrRequest(): RequestInterface
    // createRequest(method->value, uri); apply headers (null → ''); attach body stream;
    // then connector->handlePsrRequest() then request->handlePsrRequest()

    public function getFactoryCollection(): FactoryCollection
}
```

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

### Fixture Constructor

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates a Fixture for recording and replaying HTTP responses in tests. Configure name, storage, and context.

```APIDOC
## Fixture Constructor

### Description
Creates a Fixture for recording and replaying HTTP responses in tests. Configure name, storage, and context.

### Method
Constructor

### Endpoint
`new Fixture($name, $storage, $context)`

### Parameters
#### Constructor Parameters
- **$name** (string) - Optional - Fixture file name (validated against traversal); empty → `defineName()`. Default: `''`
- **$storage** (?Storage) - Optional - Storage backend. Default: `new Storage(MockConfig::getFixturePath(), true)`
- **$context** (?ArrayStoreContract) - Optional - Context merged into recorded responses. Default: `new ArrayStore()`

### Response
Returns a new Fixture instance.
```

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

### AcceptsJson boot method

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Adds an Accept: application/json header to every request. Booted automatically via the BootPlugins step in PendingRequest.

```php
public static function bootAcceptsJson(PendingRequest $pendingRequest): void
{
    $pendingRequest->headers()->add('Accept', 'application/json');
}
```

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

### getMethod() / setMethod(Method $method)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Gets or sets the HTTP method for the pending request.

```APIDOC
## getMethod() / setMethod(Method $method)

### Description
Gets or sets the HTTP method for the pending request.

### Methods
- `getMethod()` - Returns the current method.
- `setMethod(Method $method)` - Sets the method. Returns `static`.

### Parameters
- `$method` (Method) - Required - The HTTP method to set.

### Return Type
- `getMethod()`: Method
- `setMethod()`: static
```

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

### Custom sender example implementing Saloon Sender interface

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/sending.md

Example of a custom LoggingSender class that implements Saloon\Contracts\Sender. It reuses GuzzleSender's factory collection, logs the request URL and duration via error_log, and delegates send and sendAsync to GuzzleSender. The final line pre-wires the whole app with Config::setSenderResolver(fn () => new LoggingSender).

```php
<?php

use Saloon\Contracts\Sender;
use Saloon\Data\FactoryCollection;
use Saloon\Http\Response;
use Saloon\Http\PendingRequest;
use GuzzleHttp\Promise\PromiseInterface;

class LoggingSender implements Sender
{
    public function getFactoryCollection(): FactoryCollection
    {
        return (new GuzzleSender)->getFactoryCollection(); // reuse Guzzle's
    }

    public function send(PendingRequest $pendingRequest): Response
    {
        $start = microtime(true);
        $response = (new GuzzleSender)->send($pendingRequest);
        error_log($pendingRequest->getUrl() . ' took ' . (microtime(true) - $start) . 's');
        return $response;
    }

    public function sendAsync(PendingRequest $pendingRequest): PromiseInterface
    {
        return (new GuzzleSender)->sendAsync($pendingRequest);
    }
}

Config::setSenderResolver(fn () => new LoggingSender); // pre-wire the whole app
```

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

### MockClient constructor signature

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Constructor accepts an array of mock data. Keys can be request class names, connector class names, URL patterns with wildcards, or omitted integer keys for sequence entries.

```php
/**
 * @param array<\Saloon\Http\Faking\MockResponse|\Saloon\Http\Faking\Fixture|callable> $mockData
 */
public function __construct(array $mockData = [])
```

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

### Fixture constructor signature

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Constructor for the Fixture class. The name defaults to '' and is resolved from defineName() when empty. Storage defaults to a new Storage at MockConfig::getFixturePath() with true, creating the fixture directory if missing. Context defaults to a new ArrayStore().

```php
public function __construct(string $name = '', ?Storage $storage = null, ?ArrayStoreContract $context = null)
```

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

### isAsynchronous() / setAsynchronous(bool $asynchronous)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Gets or sets whether the request is asynchronous. Set to `true` by `SendsRequests::sendAsync()`.

```APIDOC
## isAsynchronous() / setAsynchronous(bool $asynchronous)

### Description
Gets or sets whether the request is asynchronous. Set to `true` by `SendsRequests::sendAsync()`.

### Methods
- `isAsynchronous()` - Returns true if the request is asynchronous.
- `setAsynchronous(bool $asynchronous)` - Sets the asynchronous flag. Returns `static`.

### Parameters
- `$asynchronous` (bool) - Required - Whether the request is asynchronous.

### Return Type
- `isAsynchronous()`: bool
- `setAsynchronous()`: static
```

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

### Using CreatesDtoFromResponse in a request

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-utility.md

Example of a request that uses the trait to create a UserDto from the response, then sends it and calls dto().

```php
<?php

use Saloon\Traits\Request\CreatesDtoFromResponse;

class GetUserRequest extends Request
{
    use CreatesDtoFromResponse;

    public function createDtoFromResponse(Response $response): mixed
    {
        return new UserDto(
            id: $response->json('id'),
            name: $response->json('name'),
        );
    }
}

$user = $connector->send(new GetUserRequest)->dto();
```

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

### MockClient::__construct

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Creates a new MockClient instance with optional mock data. The mock data can be keyed by request class names, connector class names, URL patterns, or left as a sequence with integer keys.

```APIDOC
## MockClient::__construct

### Description
Creates a new MockClient instance with optional mock data. The mock data can be keyed by request class names, connector class names, URL patterns, or left as a sequence with integer keys.

### Method
Constructor

### Signature
`public function __construct(array $mockData = [])`

### Parameters
- **$mockData** (array) - Optional - Array of mock responses, fixtures, or callables. Keys can be request class names, connector class names, URL patterns (wildcards supported), or omitted (integer keys → sequence).
```

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

### NullAuthenticator usage example

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/authenticators.md

Shows how to disable authentication for a specific request by passing a NullAuthenticator to the authenticate() method, overriding any inherited authenticator.

```php
<?php

$connector->send((new PublicEndpointRequest)->authenticate(new NullAuthenticator));
```

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

### OAuthConfig::make() and Setters

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates an OAuth configuration object and provides fluent setters for OAuth2 parameters. Use `validate()` to ensure required fields are set.

```APIDOC
## OAuthConfig::make() and Setters

### Description
Creates an OAuth configuration object and provides fluent setters for OAuth2 parameters. Use `validate()` to ensure required fields are set.

### Method
Static factory and fluent setters

### Endpoint
`OAuthConfig::make()` then setters (all fluent, `static` return)

### Parameters
#### Setter Parameters
- **setClientId(string)** - Required - Client ID; required by `validate()`
- **setClientSecret(string)** - Required - Client Secret; required by `validate()`
- **setRedirectUri(string)** - Required - Redirect URI; required by `validate(true)`
- **setAuthorizeEndpoint(string)** - Optional - Authorize endpoint. Default: `'authorize'`
- **setTokenEndpoint(string)** - Optional - Token endpoint. Default: `'token'`
- **setUserEndpoint(string)** - Optional - User endpoint. Default: `'user'`
- **setDefaultScopes(array<string>)** - Optional - Default scopes; merged with per-call scopes. Default: `[]`
- **setRequestModifier(callable(Request): void|null)** - Optional - Applied to every OAuth request. Default: `null`
- **setAllowBaseUrlOverride(bool)** - Optional - Allows absolute OAuth endpoints (SSRF caution). Default: `false`

### Response
Returns the OAuthConfig instance (fluent).
```

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

### MultipartValue Constructor

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates a multipart value for request bodies. Specify field name, value, filename, and headers.

```APIDOC
## MultipartValue Constructor

### Description
Creates a multipart value for request bodies. Specify field name, value, filename, and headers.

### Method
Constructor

### Endpoint
`new MultipartValue($name, $value, $filename, $headers)`

### Parameters
#### Constructor Parameters
- **$name** (string) - Required - Field name
- **$value** (StreamInterface|resource|string|int) - Required - Field contents
- **$filename** (?string) - Optional - File name. Default: `null`
- **$headers** (array<string, mixed>) - Optional - Part headers. Default: `[]`

### Response
Returns a new MultipartValue instance.
```

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

### GuzzleSender Constructor

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates a GuzzleSender with default Guzzle client options. Override per-request via Guzzle request options.

```APIDOC
## GuzzleSender Constructor

### Description
Creates a GuzzleSender with default Guzzle client options. Override per-request via Guzzle request options.

### Method
Constructor

### Endpoint
`new GuzzleSender()`

### Parameters
#### Constructor Parameters
Takes no arguments. The Guzzle client is created with these defaults (all overridable per-request via `config()` keys, i.e. Guzzle request options):

| Guzzle option | Value |
|---|---|
| `crypto_method` | `Config::$defaultTlsMethod` |
| `connect_timeout` | `Config::$defaultConnectionTimeout` |
| `timeout` | `Config::$defaultRequestTimeout` |
| `http_errors` | `true` |
| `handler` | `HandlerStack::create()` (exposed via `getHandlerStack()`/`setHandlerStack()`/`addMiddleware()`) |

### Response
Returns a new GuzzleSender instance.
```

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

### getUrl() / setUrl(string $url)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Gets or sets the URL for the pending request. `setUrl` replaces the URL; query parameters from `query()` are still merged in by `getUri()`.

```APIDOC
## getUrl() / setUrl(string $url)

### Description
Gets or sets the URL for the pending request. `setUrl` replaces the URL; query parameters from `query()` are still merged in by `getUri()`.

### Methods
- `getUrl()` - Returns the current URL as a string.
- `setUrl(string $url)` - Sets the URL. Returns `static`.

### Parameters
- `$url` (string) - Required - The new URL.

### Return Type
- `getUrl()`: string
- `setUrl()`: static
```

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

### Fixture::getContext

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Returns the whole context ArrayStore or a single key value.

```APIDOC
## Fixture::getContext

### Description
Returns the whole context ArrayStore or a single key value.

### Method
public

### Signature
`public function getContext(?string $key = null): mixed`

### Parameters
- **$key** (?string) - Optional - The key to retrieve. If null, returns the whole context.

### Returns
- **mixed** - The context value or the entire ArrayStore.
```

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

### MiddlewarePipeline constructor and clone

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/middleware-pipeline.md

Constructor initializes three Pipeline instances (request, response, fatal). __clone deep-clones all three pipelines for request/connector cloning safety.

```php
public function __construct()
// requestPipeline = new Pipeline; responsePipeline = new Pipeline; fatalPipeline = new Pipeline

public function __clone(): void
// deep-clones all three pipelines (request/connector cloning safety)
```

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

### getFakeResponse() / setFakeResponse(?FakeResponse $fakeResponse) / hasFakeResponse()

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Gets, sets, or checks for a fake response. When a fake response is set, `SendsRequests` bypasses the sender and builds the response from the fake.

```APIDOC
## getFakeResponse() / setFakeResponse(?FakeResponse $fakeResponse) / hasFakeResponse()

### Description
Gets, sets, or checks for a fake response. When a fake response is set, `SendsRequests` bypasses the sender and builds the response from the fake.

### Methods
- `getFakeResponse()` - Returns the current fake response or null.
- `setFakeResponse(?FakeResponse $fakeResponse)` - Sets the fake response. Returns `static`.
- `hasFakeResponse()` - Returns true if a fake response is set.

### Parameters
- `$fakeResponse` (?FakeResponse) - Required - The fake response to set, or null to clear.

### Return Type
- `getFakeResponse()`: ?FakeResponse
- `setFakeResponse()`: static
- `hasFakeResponse()`: bool
```

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

### GetUserRequest

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/oauth2.md

Creates a request to fetch the authenticated user's profile from the user endpoint. This request is sent as a GET request with no request body.

```APIDOC
## GetUserRequest

### Description
Creates a request to fetch the authenticated user's profile from the user endpoint. This request is sent as a GET request with no request body.

### Method
GET

### Endpoint
`oauthConfig->getUserEndpoint()`

### Parameters
#### Constructor Parameters
- **oauthConfig** (OAuthConfig) - Required - The OAuth configuration containing the user endpoint URL.

### Request Example
No request body is sent.

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **name** (string) - The user's full name.
- **email** (string) - The user's email address.
- **avatar** (string) - Optional. The user's avatar URL.

#### Response Example
```json
{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "avatar": "https://example.com/avatar.jpg"
}
```
```

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

### MockResponse::make() / FakeResponse::make()

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates a mock or fake response for testing HTTP requests. Configure body, status code, and headers.

```APIDOC
## MockResponse::make() / FakeResponse::make()

### Description
Creates a mock or fake response for testing HTTP requests. Configure body, status code, and headers.

### Method
Static factory

### Endpoint
`MockResponse::make($body, $status, $headers)` / `FakeResponse::make($body, $status, $headers)`

### Parameters
#### Factory Parameters
- **$body** (array|string) - Optional - Array bodies become `JsonBodyRepository`; strings become `StringBodyRepository`. Default: `[]`
- **$status** (int) - Optional - HTTP status code. Default: `200`
- **$headers** (array<string, mixed>) - Optional - Response headers. Default: `[]`

### Response
Returns a new MockResponse or FakeResponse instance.
```

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

### Customizing failure handling in a Connector

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-utility.md

Example of overriding hasRequestFailed() and getRequestException() in a Connector to treat a 200 response with an error envelope as failure and to return a custom exception.

```php
<?php

class ApiConnector extends \Saloon\Http\Connector
{
    public function hasRequestFailed(\Saloon\Http\Response $response): ?bool
    {
        // treat 200-with-error-envelope as failure
        if ($response->status() === 200 && $response->json('error')) {
            return true;
        }

        return parent::hasRequestFailed($response);
    }

    public function getRequestException($response, ?\Throwable $senderException): ?\Throwable
    {
        return new \RuntimeException('API said: ' . $response->json('error.message'));
    }
}
```

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

### HasTimeout boot and getter methods

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Boot method merges connect and request timeouts into request options. Getter methods return the class property if set, otherwise the default from Config. Timeouts are in seconds.

```php
public function bootHasTimeout(PendingRequest $pendingRequest): void
// config()->merge([RequestOptions::CONNECT_TIMEOUT => getConnectTimeout(), RequestOptions::TIMEOUT => getRequestTimeout()])

public function getConnectTimeout(): float
// property_exists($this, 'connectTimeout') ? $this->connectTimeout : Config::$defaultConnectionTimeout

public function getRequestTimeout(): float
// property_exists($this, 'requestTimeout') ? $this->requestTimeout : Config::$defaultRequestTimeout
```

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

### FatalRequestException class

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/errors.md

Thrown when the sender cannot obtain a response (connection failure, TLS/SSL error, network timeout). Use getPrevious() to get the original exception and getPendingRequest() to access the pending request.

```php
class FatalRequestException extends SaloonException
{
    public function __construct(Throwable $originalException, PendingRequest $pendingRequest)
    // getPendingRequest(): PendingRequest
}
```

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

### __clone() deep-clones mutable properties

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/request.md

Clones query, headers, config, delay, and middlewarePipeline so cloned requests don't share state, useful for concurrent pools.

```php
public function __clone(): void
{
    if (isset($this->query)) {
        $this->query = clone $this->query;
    }
    if (isset($this->headers)) {
        $this->headers = clone $this->headers;
    }
    if (isset($this->config)) {
        $this->config = clone $this->config;
    }
    if (isset($this->delay)) {
        $this->delay = clone $this->delay;
    }
    if (isset($this->middlewarePipeline)) {
        $this->middlewarePipeline = clone $this->middlewarePipeline;
    }
}
```

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

### MockClient::global

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Registers a process-wide mock client used as a last-resort fallback by PendingRequest.

```APIDOC
## MockClient::global

### Description
Registers a process-wide mock client used as a last-resort fallback by PendingRequest.

### Method
global (static)

### Signature
`public static function global(array $mockData = []): MockClient`

### Parameters
- **$mockData** (array) - Optional - Array of mock responses, fixtures, or callables.

### Returns
- **MockClient** - The created MockClient instance.
```

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

### sendAsync(Request $request, ?MockClient $mockClient = null): PromiseInterface

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-sending.md

Asynchronously sends a request. Wraps creation in a Guzzle task so the PendingRequest is built when the promise starts. No retry logic in the async path.

```APIDOC
## sendAsync(Request $request, ?MockClient $mockClient = null): PromiseInterface

### Description
Asynchronously sends a request. Wraps creation in a Guzzle task so the PendingRequest is built when the promise starts. No retry logic in the async path.

### Method
sendAsync

### Parameters
- **$request** (Request) - Required - Request to send
- **$mockClient** (?MockClient) - Optional - Mock client override for this call

### Returns
PromiseInterface
```

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

### Fixture::getMockResponse

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Reads the fixture file and returns a MockResponse, applying merge and through transformations. Returns null (triggering recording) when the file is missing and throwing is disabled; throws FixtureMissingException otherwise.

```APIDOC
## Fixture::getMockResponse

### Description
Reads the fixture file and returns a MockResponse, applying merge and through transformations.

### Method
public

### Signature
`public function getMockResponse(): ?MockResponse`

### Returns
- **?MockResponse** - The mock response, or null if the fixture is missing and throwing is disabled.
```

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

### object(string|int|null $key = null, mixed $default = null)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/response.md

Like json() but decodes the body to an object. Key lookup uses dot-notation via ObjectHelpers::get.

```APIDOC
## object(string|int|null $key = null, mixed $default = null)

### Description
Like json() but decodes the body to an object. Key lookup uses dot-notation via ObjectHelpers::get.

### Method
object()

### Signature
```php
public function object(string|int|null $key = null, mixed $default = null): mixed
```

### Parameters
- **$key** (string|int|null) - Optional - Dot-notation item key; null returns the whole object.
- **$default** (mixed) - Optional - Returned when the key is absent.

### Returns
- **mixed** - The decoded object, or the value at the given key, or the default.
```

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

### Common authenticator usage

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/authenticators.md

Demonstrates per-request authentication override with TokenAuthenticator, combining multiple authenticators with MultiAuthenticator, and handling authentication failures. The combined example uses TokenAuthenticator and QueryAuthenticator together. The try/catch block catches RequestException for 401/403 responses indicating API-level authentication failure.

```php
<?php

use Saloon\Http\Auth\TokenAuthenticator;
use Saloon\Http\Auth\MultiAuthenticator;
use Saloon\Http\Auth\QueryAuthenticator;

// Per-request override
$response = $connector->send(
    (new GetServersRequest)->authenticate(new TokenAuthenticator('t0ken'))
);

// Combined
$auth = new MultiAuthenticator(
    new TokenAuthenticator('t0ken'),
    new QueryAuthenticator('api_key', 'k3y'),
);

try {
    $connector->authenticate($auth)->send(new ProtectedRequest);
} catch (\Saloon\Exceptions\Request\RequestException $e) {
    // 401/403 etc. — authentication failed at the API level
}
```

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

### HasMockClient trait definition

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-sending.md

Trait used by Connector, Request, and PendingRequest to manage a mock client. Provides methods to set, get, and check for a mock client. PendingRequest resolves the mock client in this order: constructor arg → request → connector → MockClient::getGlobal().

```php
trait HasMockClient
{
    protected ?MockClient $mockClient = null;

    public function withMockClient(MockClient $mockClient): static   // set
    public function getMockClient(): ?MockClient                     // read
    public function hasMockClient(): bool                            // instanceof check
}
```

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

### MockClient::getGlobal

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Returns the global mock client if set.

```APIDOC
## MockClient::getGlobal

### Description
Returns the global mock client if set.

### Method
getGlobal (static)

### Signature
`public static function getGlobal(): ?MockClient`

### Returns
- **?MockClient** - The global mock client, or null if not set.
```

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

### AcceptsJson::bootAcceptsJson

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Boot method for the AcceptsJson plugin trait. Automatically adds an 'Accept: application/json' header to the pending request.

```APIDOC
## bootAcceptsJson(PendingRequest $pendingRequest): void

### Description
Boot method for the AcceptsJson plugin trait. Automatically adds an 'Accept: application/json' header to the pending request.

### Method
bootAcceptsJson

### Parameters
- **$pendingRequest** (PendingRequest) - Required - The pending request instance.

### Behavior
Adds the header `Accept: application/json` to the request headers.
```

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

### CreateUserRequest with HasJsonBody and middleware body mutation

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/body-repositories.md

Shows a request using HasJsonBody to define a default JSON body, then a middleware example that mutates the merged body of a pending request by adding a timestamp if the body is a JsonBodyRepository. Note that ArrayBodyRepository::toStream() always throws LogicException, and JsonBodyRepository throws JsonException on invalid data during toStream().

```php
<?php

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

class CreateUserRequest extends \Saloon\Http\Request implements HasBody
{
    use HasJsonBody;

    protected function defaultBody(): array
    {
        return ['name' => 'Sam'];
    }
}

// In middleware: mutate the merged body of a pending request
$connector->middleware()->onRequest(function (\Saloon\Http\PendingRequest $pendingRequest) {
    $body = $pendingRequest->body();

    if ($body instanceof \Saloon\Repositories\Body\JsonBodyRepository) {
        $body->add('timestamp', time());
    }
});
```

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

### Pool Constructor

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/configuration.md

Creates a new Pool instance for sending multiple requests concurrently. Configure concurrency, response handlers, and exception handlers.

```APIDOC
## Pool Constructor

### Description
Creates a new Pool instance for sending multiple requests concurrently. Configure concurrency, response handlers, and exception handlers.

### Method
Constructor

### Endpoint
`new Pool($connector, $requests, $concurrency, $responseHandler, $exceptionHandler)`

### Parameters
#### Constructor Parameters
- **$connector** (Connector) - Required - Connector used to send the pooled requests
- **$requests** (iterable<Request|PromiseInterface>|callable(Connector): iterable) - Optional - Requests to send; callable receives the connector and returns an iterable. Default: `[]`
- **$concurrency** (int|callable(int $pendingRequests): int) - Optional - Max simultaneous requests; callable receives pending-request count. Default: `5`
- **$responseHandler** (callable(Response, array-key $key, PromiseInterface $poolAggregate): void|null) - Optional - Called for each fulfilled request. Default: `null`
- **$exceptionHandler** (callable(mixed $reason, array-key $key, PromiseInterface $poolAggregate): void|null) - Optional - Called for each rejected request. Default: `null`

### Response
Returns a new Pool instance.
```

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

### ChecksForHasBody boot method

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/traits-body-and-plugins.md

Throws BodyException if the request or connector does not implement HasBody. The connector may carry the body instead of the request.

```php
/**
 * @throws \Saloon\Exceptions\BodyException
 */
public function bootChecksForHasBody(PendingRequest $pendingRequest): void
{
    if ($pendingRequest->getRequest() instanceof HasBody || $pendingRequest->getConnector() instanceof HasBody) {
        return;
    }

    throw new BodyException(sprintf('You have added a body trait without implementing `%s` on your request or connector.', HasBody::class));
}
```

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

### SpotifyConnector with AuthorizationCodeGrant and OAuth2 flow

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/oauth2.md

Real-world example of using Saloon's AuthorizationCodeGrant trait with a Spotify connector. Configure OAuth2 endpoints via defaultOauthConfig, generate an authorization URL, exchange the code for an access token, handle InvalidStateException for CSRF mismatches, refresh the token if refreshable, and use the authenticated connector. Note the setAllowBaseUrlOverride(true) because the endpoints are absolute and differ from the base URL.

```php
<?php

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

class SpotifyConnector extends Connector
{
    use AuthorizationCodeGrant;

    public function __construct(protected string $clientId, protected string $clientSecret) {}

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

    protected function defaultOauthConfig(): \Saloon\Helpers\OAuth2\OAuthConfig
    {
        return \Saloon\Helpers\OAuth2\OAuthConfig::make()
            ->setClientId($this->clientId)
            ->setClientSecret($this->clientSecret)
            ->setRedirectUri('https://app.example.com/callback')
            ->setAuthorizeEndpoint('https://accounts.spotify.com/authorize')
            ->setTokenEndpoint('https://accounts.spotify.com/api/token')
            ->setAllowBaseUrlOverride(true); // these are absolute ≠ base URL
    }
}

$connector = new SpotifyConnector('id', 'secret');

// 1) redirect the user:
$url = $connector->getAuthorizationUrl(scopes: ['user-read-email'], state: 'csrf-token');

// 2) exchange the code (validate state in your controller!):
try {
    $auth = $connector->getAccessToken($code, $stateFromCallback, 'csrf-token');
} catch (\Saloon\Exceptions\InvalidStateException $e) {
    // CSRF mismatch — abort
} catch (\Saloon\Exceptions\Request\RequestException $e) {
    // provider rejected the code
}

if ($auth->isRefreshable()) {
    $auth = $connector->refreshAccessToken($auth);
}

$userResponse = $connector->getUser($auth);
```

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

### createException() protected method signature

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/response.md

Protected internal builder used by toException() to create the exception.

```php
protected function createException(): Throwable
```

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

### __construct(Connector $connector, Request $request, ?MockClient $mockClient = null)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Creates a new PendingRequest instance. All parameters are required except $mockClient, which defaults to null and falls back to request → connector → global mock client.

```APIDOC
## Constructor

### `__construct(Connector $connector, Request $request, ?MockClient $mockClient = null)`

### Description
Creates a new PendingRequest instance. All parameters are required except `$mockClient` (default `null`, falling back to request → connector → global mock client).

### Parameters
- `$connector` (Connector) - Required - The connector instance.
- `$request` (Request) - Required - The request instance.
- `$mockClient` (?MockClient) - Optional - Mock client instance, defaults to null.

### Return Type
void
```

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

### MockClient::addResponses

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Bulk adds multiple mock responses to the client. Integer keys become sequence entries.

```APIDOC
## MockClient::addResponses

### Description
Bulk adds multiple mock responses to the client. Integer keys become sequence entries.

### Method
addResponses

### Signature
`public function addResponses(array $responses): void`

### Parameters
- **$responses** (array) - Required - Array of mock responses, fixtures, or callables.
```

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

### executeFatalPipeline(FatalRequestException $throwable)

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/pending-request.md

Runs fatal middleware (`MiddlewarePipeline::onFatalException` pipes) over the throwable.

```APIDOC
## executeFatalPipeline(FatalRequestException $throwable)

### Description
Runs fatal middleware (`MiddlewarePipeline::onFatalException` pipes) over the throwable.

### Method
executeFatalPipeline

### Parameters
- `$throwable` (FatalRequestException) - Required - The exception to process.

### Return Type
void
```

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

### Fixture::defineName

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Hook to define the fixture name. Default returns an empty string.

```APIDOC
## Fixture::defineName

### Description
Hook to define the fixture name.

### Method
protected

### Signature
`protected function defineName(): string`

### Returns
- **string** - The fixture name.
```

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

### __clone()

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/request.md

Deep-clones the mutable property stores (query, headers, config, delay, middlewarePipeline) so cloned requests don't share state.

```APIDOC
## __clone()

### Description
Deep-clones the mutable property stores (query, headers, config, delay, middlewarePipeline) so cloned requests don't share state.

### Method
N/A

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **void** - No return value.

#### Response Example
```php
$clonedRequest = clone $request;
```
```

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

### BasicAuthenticator constructor

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/authenticators.md

Creates a basic authenticator with username and password. The set() method adds an Authorization header with Basic base64(username:password).

```php
public function __construct(
    public string $username,
    public string $password,
) {}
```

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

### MockClient::assertNothingSent

Source: https://github.com/saloonphp/saloon/blob/v4/_autodocs/api-reference/faking.md

Fails if any response was recorded.

```APIDOC
## MockClient::assertNothingSent

### Description
Fails if any response was recorded.

### Method
assertNothingSent

### Signature
`public function assertNothingSent(): void`
```
Tokens:
Raw