Saloon
GithubOfficial BookSponsor
v3
v3
  • 🀠Saloon
  • Upgrade
    • πŸͺ„What's new in v3
    • 🌳Upgrading from v2
  • The Basics
    • ⬇️Installation
    • πŸ”ŒConnectors
    • βœ‰οΈRequests
    • πŸ”Authentication
    • 🎁Sending Body/Data
      • JSON Body
      • Multipart Form Body
      • XML Body
      • URL Encoded Body (Form)
      • String / Plain Text Body
      • Stream Body
    • πŸš€Sending Requests
    • πŸ“‘Responses
    • πŸ”₯Handling Failures
    • πŸ”ŽDebugging
    • βœ…Testing
  • Digging Deeper
    • πŸ›ΈData Transfer Objects
    • ✨Building SDKs
    • ☝️Solo Requests
    • 🎯Retrying Requests
    • ⏸️Delaying Requests
    • 🏎️Concurrency & Pools
    • πŸ”‘OAuth2
      • Authorization Code Grant
      • Client Credentials Grant
    • πŸ’«Middleware
    • ⛩️PSR Support
  • Installable Plugins
    • πŸ“šPagination
      • Paged Pagination
      • Limit/Offset Pagination
      • Cursor Pagination
      • Custom Pagination
    • β›΅Laravel Plugin
    • πŸ”Caching
    • β›”Rate Limit Handler
    • 🏭Auto SDK Generator
    • 🀠Lawman
    • πŸ‡XML Wrangler
    • πŸ—οΈBuilding Your Own Plugins
  • Conclusion
    • πŸ“˜Official Book!
    • πŸ“”How-to Guides
      • Improving Speed With Laravel
      • Per-request Authentication
    • πŸ“–Tutorials & Blog Posts
    • πŸŽ–οΈShowcase
    • πŸ’₯Known Issues
    • πŸ€—Credits
    • ❀️Support Saloon
Powered by GitBook
On this page
  • Getting Started
  • Headers
  • Timeout
  • Constructor Arguments
  • HTTP Client Config
Edit on GitHub
  1. The Basics

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

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);
PreviousInstallationNextRequests

Last updated 1 year ago

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

πŸ”Œ
Guzzle
Click here to see a list of the available options Guzzle provide.