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

Are you building an integration for just one request?

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.

Getting Started

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 the Laravel Saloon Plugin? Use the following Artisan command to create a connector!

php artisan saloon:connector <Integration Name> <Connector Name>

Default Headers and Query Parameters

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',
        ];
    }
}

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
        ];
    }
}

Default HTTP Client Configuration

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.

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

<?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,
        ];
    }
}

Using Constructor Arguments

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

<?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); 
    }
}

Usage

$forge = new ForgeConnector('api-token');

This example uses a method withTokenAuth which is documented on the authentication page.