Files
alfa-bank-sdk/_docs/laravel-libs/saloon-docs/the-basics/connectors.md

119 lines
3.2 KiB
Markdown

# 🔌 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/Integrations`folder. 
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
<?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.
<pre class="language-php"><code class="lang-php">class ForgeConnector extends Connector
{
// ...
<strong> protected function defaultHeaders(): array
</strong> {
return [
'Content-Type' => 'application/json',
'Accept' => 'application/json',
];
}
}
</code></pre>
You can also use the `headers` method on a connector instance.
```php
$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.
```php
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.
```php
class ForgeConnector extends Connector
{
public function __construct(protected readonly string $baseUrl) {
//
}
public function resolveBaseUrl(): string
{
return $this->baseUrl;
}
}
```
```php
$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](https://github.com/guzzle/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.](https://docs.guzzlephp.org/en/stable/request-options.html)
```php
class ForgeConnector extends Connector
{
// ...
public function defaultConfig(): array
{
return [
'stream' => true,
];
}
}
```
You can also use the `config` method on a connector instance.
```php
$forge = new ForgeConnector;
$forge->config()->add('stream', true);
```