connectors.md

🔌 Connectors

Connectors are classes which define an API integration's properties like its URL and headers. Any behaviour that should be used on every request like authentication should be defined in a connector. You should have a separate connector for each API integration.

Getting Started

You should establish a standard place to keep your API connectors. For example in Laravel, a sensible place would be to place them inside the App/Http/Integrationsfolder.

Create a new class and extend the abstract Connector class. You will then need to define a method resolveBaseUrl. This is the URL that points to the API.

<?php

use Saloon\Http\Connector;

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

If you have installed the Laravel plugin, you can use the php artisan saloon:connector command to create a connector.

Headers

Most API integrations will have common headers used by all of its requests. You can extend the defaultHeaders method to define the headers.

class ForgeConnector extends Connector
{
    // ...

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

You can also use the headers method on a connector instance.

$forge = new ForgeConnector;

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

Timeout

By default, Saloon will have a connection timeout of 10 seconds and a request timeout of 30 seconds. You can customise this by using the HasTimeout trait and specifying a connectTimeout and requestTimeout property.

use Saloon\Traits\Plugins\HasTimeout;

class ForgeConnector extends Connector
{
    use HasTimeout;
    
    protected int $connectTimeout = 60;
    
    protected int $requestTimeout = 120;
}

Constructor Arguments

Since connectors are just classes, you can define a constructor to populate its default properties. For example, if the URL changes per user of your application you can define this as a constructor argument.

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

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

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

HTTP Client Config

The connector uses a HTTP client to send the request. By default, this client is Guzzle. If you would like to define Guzzle config options then you can extend the defaultConfig method.

Click here to see a list of the available options Guzzle provide.

class ForgeConnector extends Connector
{
    // ...

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

You can also use the config method on a connector instance.

$forge = new ForgeConnector;

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