Що дає Saloon для побудови SDK стороннього API і чим він кращий за прямі виклики Http?

Saloon - бібліотека для PHP (з інтеграцією в Laravel), що структурує роботу з API у класи: конектор описує API загалом, запит - один ендпойнт.

use Saloon\Http\Connector;
use Saloon\Traits\Plugins\AcceptsJson;

final class CrmConnector extends Connector
{
    use AcceptsJson;

    public ?int $tries = 3;
    public ?int $retryInterval = 500;
    public ?bool $useExponentialBackoff = true;

    public function __construct(private readonly string $token) {}

    public function resolveBaseUrl(): string
    {
        return 'https://crm.example.com/api/v2';
    }

    protected function defaultAuth(): TokenAuthenticator
    {
        return new TokenAuthenticator($this->token);
    }
}

use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;

final class GetDeal extends Request
{
    protected Method $method = Method::GET;

    public function __construct(private readonly int $id) {}

    public function resolveEndpoint(): string
    {
        return "/deals/{$this->id}";
    }

    public function createDtoFromResponse(Response $response): Deal
    {
        return Deal::fromArray($response->json('data'));
    }
}

$deal = $connector->send(new GetDeal(42))->dto();   // Deal, а не масив

Що дає порівняно з Http:: у класі-клієнті:

• один запит - один клас: ендпойнт, метод, тіло, заголовки, перетворення відповіді в DTO живуть разом. Великий API (десятки ендпойнтів) не перетворюється на клас-клієнт на тисячу рядків;
• DTO на виході (createDtoFromResponse + dto()) - решта застосунку не бачить формату провайдера;
• повтори, автентифікація, пагінація, OAuth2 - готові механізми на рівні конектора;
• тести: MockClient з відповідями для конкретних класів запитів і фікстури - записані справжні відповіді, що відтворюються в тестах;
• middleware на рівні конектора - логування, метрики, ідентифікатори кореляції в одному місці.

Як не перестаратися:

• для двох-трьох викликів Saloon - зайва церемонія; макрос чи невеликий клас-клієнт простіші;
• DTO мають відображати потреби вашого коду, а не повністю копіювати відповідь провайдера: мапінг лише потрібних полів, перетворення типів (дати, гроші в мінімальних одиницях, енуми статусів) і явна обробка відсутніх полів;
• не тягнути SDK у предметну область: сервіси застосунку залежать від вашого інтерфейсу (CrmGateway), а Saloon - деталь його реалізації. Тоді зміна провайдера чи бібліотеки не зачіпає бізнес-логіку.

Коли Saloon особливо доречний: ключова інтеграція з великою кількістю ендпойнтів, кілька інтеграцій з однаковими підходами в команді, публікація власного SDK для свого API.

Докладніше в документації: Saloon: конектори