Настройте SDK

PHP

С какими опциями собирается SDK, для чего каждая из них и какую единственную переменную окружения он читает.

3 мин чтения

SDK собирают один раз, с несколькими опциями, и каждый вызов их использует: ключ, таймауты и повторы запроса, логгер, место, куда уходят спаны, и секрет ваших вебхуков. Эта страница перечисляет опции и говорит, для чего каждая из них.

Собрать SDK

PHP

use Psr\Log\AbstractLogger;
use Slen\Sdk\SlenConfig;
use Slen\Sdk\SlenSdk;

// Stands in for the PSR-3 logger of your application: this one prints what went wrong.
$logger = new class extends AbstractLogger {
    public function log($level, string|\Stringable $message, array $context = []): void
    {
        if ($level === 'warning' || $level === 'error') {
            echo $level, ' ', $message, PHP_EOL;
        }
    }
};

// SlenConfig reads no environment variable: the key is passed.
$slen = SlenSdk::create(new SlenConfig(
    apiKey: (string) getenv('SLEN_API_KEY'),
    timeout: 120.0,
    connectTimeout: 3.0,
    retries: 3,
    logger: $logger,
));

SlenConfig не читает переменных окружения: передайте ключ, как пример читает его из SLEN_API_KEY. Пустой ключ, таймаут не больше нуля, отрицательное число повторов и допуск вебхука меньше одной секунды он отклоняет с InvalidArgumentException там, где собирают SDK, а не на первом вызове. Сборка SDK не обращается к сети. Ключ и секрет вебхука не видны ни в дампе конфигурации, ни в трассировке стека. В приложении на Laravel сервис-провайдер собирает SDK из файла конфигурации — Интеграция с Laravel.

SDK из примера запускает флоу, как любой другой. Его логгер печатает строку, только когда запрос отправляется ещё раз или не удаётся.

PHP

use Slen\Sdk\Modules\Operations\Options\ExecuteOptions;

$execution = $slen->operations()->execute(
    'generate_email',
    ['messages' => [['role' => 'user', 'content' => 'Write a short follow-up email.']]],
    new ExecuteOptions(idempotencyKey: 'order-42:email'),
);

echo $execution->status->value, PHP_EOL;

Опции

Опция	Тип	По умолчанию
`apiKey` обязательно	`string`	нет
`timeout`	`float`	`self::DEFAULT_TIMEOUT`
`connectTimeout`	`float`	`self::DEFAULT_CONNECT_TIMEOUT`
`retries`	`int`	`self::DEFAULT_RETRIES`
`logger`	`Psr\Log\LoggerInterface`	`new \Psr\Log\NullLogger(…)`
`spanRecorder`	`Slen\Sdk\Observability\SpanRecorderInterface`	`new \Slen\Sdk\Observability\NullSpanRecorder(…)`
`httpClient`	`?Psr\Http\Client\ClientInterface`	`null`
`requestFactory`	`?Psr\Http\Message\RequestFactoryInterface`	`null`
`streamFactory`	`?Psr\Http\Message\StreamFactoryInterface`	`null`
`webhookSecret`	`?string`	`null`
`webhookToleranceSeconds`	`int`	`self::DEFAULT_WEBHOOK_TOLERANCE_SECONDS`

Таблица печатает значение по умолчанию так, как его пишет язык: время в Node.js — в миллисекундах, в PHP — в секундах.

Ключ — apiKey: API-ключ вашего проекта, sl_live_…. Где его выпустить, показывает статья Управление API-ключами.
Таймауты — timeoutMs в Node.js; timeout и connectTimeout в PHP. Они ограничивают одну попытку запроса — Повторы и таймауты.
Повторы — retries: сколько раз запрос отправляется ещё раз, когда ответа не было, после 429 или 503. 0 выключает повторы — Повторы и таймауты.
Журнал — logger: куда SDK пишет то, что делает, — Журнал.
Спаны — spanRecorder, а в Node.js ещё и otlp — Спаны.
Вебхуки — webhookSecret и webhookToleranceSeconds: секрет подписи вашего эндпоинта и то, насколько старой может быть подпись, — Вебхуки.

Ещё три параметра:

httpClient — клиент PSR-18, через который идут запросы. Он используется как есть, со своими таймаутами. Тест передаёт сюда дублёр из статьи Тестирование интеграции.
requestFactory, streamFactory — фабрики PSR-17, которыми создаются запросы.

Без них SDK находит то, что установлено в вашем приложении. Когда он находит Guzzle или Symfony HttpClient, он собирает этот клиент сам, с timeout и connectTimeout. Любой другой клиент сохраняет свои таймауты, и SDK пишет в свой журнал slen.config.timeout_not_applied.

Вызов принимает то, что называет его предмет, — операцию и её вход, id, сумму, — а затем один объект опций: RequestOptions или опции этого вызова, например ExecuteOptions запуска. В опциях вызова, который отправляет запрос, есть timeout и retries: они заменяют значения конфигурации только для этого вызова — Повторы и таймауты.

SlenConfig::withLogger(), SlenConfig::withSpanRecorder() и SlenConfig::withHttpClient() возвращают копию конфигурации с одним изменением. Собранный SDK не меняется: SlenSdk::withLogger() возвращает копию, которая пишет журнал в другой логгер, через тот же HTTP-клиент, — Журнал.

Тесты и локальный стек

SDK всегда обращается к публичному API Slen: адрес — константа SDK, и ничто в этом справочнике его не передаёт. Только тест или локальный стек Slen направляет SDK на другой адрес — опцией baseUrl: хост без /api — этот путь SDK добавляет сам. В приложении на Laravel такой тест задаёт значение конфигурации slen-sdk.base_url; в файле конфигурации пакета такого ключа нет.

Что читать дальше

Повторы и таймауты — что SDK отправляет ещё раз сам и что ограничивает каждый таймаут.
Журнал — что SDK пишет в ваш логгер.
Интеграция с Laravel — SDK, собранный из файла конфигурации приложения на Laravel.
Тестирование интеграции — SDK, который отвечает из тестового дублёра, без сети.

Собрано из openapi b070e1f, sdk contract 6a2e0e0, php 4089db3, node 0fa87be