🔌
Connectors
Connectors are classes that hold the basic requirements of an API integration. Connectors communicate with the HTTP client (Sender). A connector expects a Base URL to be defined, but you can also register defaults that would be shared with all your requests, like headers or HTTP client config.
Saloon connectors are great for most API integrations; however, you may not need a connector if you make an API integration with only one request. If this is your scenario, read through the "Solo Request" section. Creating a solo request means you don't need to create a connector.
First, create a directory for your API integrations. Once you have a chosen directory, create a class that extends the
Connector abstract class. After that, extend the resolveBaseUrl function.See the example connector for Laravel Forge, an API for server management. We'll name it
Forge for the best readability.<?php
use Saloon\Http\Connector;
class ForgeConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://forge.laravel.com/api/v1';
}
}
Using Laravel? Use the artisan command to create a connector easily.
php artisan saloon:connector <Integration Name> <Connector Name>
Most API integrations will have headers that should be shared with every request, like the
Content-Type or the Accept headers. Some API integrations may even have default query parameters to be applied to every request. Saloon allows you to define default properties like these easily.To add default headers, you can extend the
defaultHeaders method to your connector. This method expects a keyed array to be returned. You may use an array in the value of a header for multiple header values.<?php
use Saloon\Http\Connector;
class ForgeConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://forge.laravel.com/api/v1';
}
protected function defaultHeaders(): array
{
return [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Multiple-Values-Header' => ['Value1', 'Value2'], // Value1;Value2
];
}
}
You may also add a
defaultQuery method to your connector to specify default query parameters for every request. This method expects a keyed array to be returned.<?php
use Saloon\Http\Connector;
class ForgeConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://forge.laravel.com/api/v1';
}
protected function defaultQuery(): array
{
return [
'per_page' => 500, // ?per_page=500
];
}
}
You may want to define custom options to send to the HTTP client. For example, you may want to register a default timeout of 60 seconds for every request. Saloon uses Guzzle as the default HTTP client, so that you may use any of Guzzle’s options inside the
defaultConfig method. This method expects a keyed array to be returned.<?php
use Saloon\Http\Connector;
class ForgeConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://forge.laravel.com/api/v1';
}
public function defaultConfig(): array
{
return [
'timeout' => 60,
];
}
}
You may add properties to your connector class and use a constructor to provide variables into the connector instance, like an API token. This is great when building SDK-style classes.
Definition
Usage
<?php
use Saloon\Http\Connector;
class ForgeConnector extends Connector
{
public function resolveBaseUrl(): string
{
return 'https://forge.laravel.com/api/v1';
}
public function __construct(
protected string $apiToken,
){
$this->withTokenAuth($this->apiToken);
}
}
$forge = new ForgeConnector('api-token');
Last modified 1mo ago