Используйте SDK в приложении на Laravel

PHP SDK поставляется с сервис-провайдером для Laravel. Он читает настройки SDK из окружения вашего приложения, собирает из них один SDK и кладёт его в контейнер. Ваш код получает этот SDK по типу или вызывает его через фасад Slen.

Настроить

Laravel сам находит сервис-провайдер и фасад пакета через обнаружение пакетов, как только пакет установлен, — команду установки даёт статья Установка.

SLEN_API_KEY=sl_live_…

php artisan vendor:publish --tag=slen-sdk-config

Файл конфигурации

• Ключ файла читает переменную, которую называет таблица. Без переменной у него значение по умолчанию.

• Последняя колонка — опция SDK, которой становится ключ. Для чего каждая опция, говорит статья Конфигурация.

• SLEN_LOG_CHANNEL называет канал из config/logging.php, в который идёт журнал SDK. Без неё журнал идёт в логгер вашего приложения — Журнал.

• SLEN_SPANS=log пишет спаны в тот же логгер, на уровне, который называет SLEN_SPAN_LEVEL. Любое другое значение никуда их не пишет. Чтобы отправлять их куда-то ещё, привяжите в контейнере свой записывающий к Slen\Sdk\Observability\SpanRecorderInterface — Спаны.

• SLEN_WEBHOOK_SECRET — секрет подписи, которым вебхуки SDK проверяют доставки, — Вебхуки.

• Значения проверяются, когда SDK впервые берут из контейнера: при пустом ключе или таймауте, равном нулю или не являющемся числом, там выбрасывается InvalidArgumentException.

Обратиться к Slen

Фасад вызывает SDK из контейнера. Каждый модуль SDK — метод фасада.

use Slen\Sdk\Laravel\Slen;
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;

SDK один на всё приложение. Любой класс, который собирает контейнер, — контроллер, задача, команда — может получить его по типу, Slen\Sdk\SlenSdk, в конструкторе или в методе. Вне такого класса попросите его у контейнера.

use Slen\Sdk\SlenSdk;

$slen = app(SlenSdk::class);

$customer = $slen->customers()->get('user_8421');

foreach ($customer->accounts as $account) {
    echo $account->creditType, ' ', $account->available, PHP_EOL;
}

У SDK нет статического состояния, поэтому он безопасен в воркере, который обслуживает много запросов, — Запустить под Octane.

В тесте вашего приложения привяжите Slen\Sdk\SlenSdk к SDK, собранному на тестовом дублёре из статьи Тестирование интеграции, вместо того, который собирает провайдер.

Запустить под Octane

Под Laravel Octane — на FrankenPHP, RoadRunner или Swoole — воркер обслуживает много запросов один за другим, и SDK из контейнера может жить столько же, сколько воркер.

• У SDK нет статического состояния, и после сборки он не меняется, поэтому один запрос ничего не оставляет в нём следующему.

• Чтобы писать журнал одного запроса в его собственный логгер, возьмите копию: SlenSdk::withLogger() возвращает новый SDK поверх того же HTTP-клиента, а SDK из контейнера сохраняет свой логгер — Журнал.

• Перечислите SlenSdk и SlenConfig в warm файла config/octane.php. Тогда воркер собирает SDK при старте, и его HTTP-клиент держит соединения открытыми от одного запроса к другому.

• Воркер читает файл конфигурации один раз. После изменения окружения или config/slen-sdk.php перезапустите воркеры командой php artisan octane:reload.

• Не ждите запуск внутри запроса: ожидание спит в воркере столько, сколько идёт запуск. Отправьте запуск через operations.executeAsync() и читайте результат из вебхука execution.finished или в задаче вашей очереди — Асинхронные запуски и ожидание.

• Дайте запуску внутри запроса свой таймаут и своё число повторов, чтобы он не длился дольше запроса, — Повторы и таймауты.

• Один SDK обращается к Slen с одним API-ключом. Приложение, которое обращается несколькими ключами, собирает по SDK на каждый и держит их в контейнере, а не в своём статическом свойстве.

• FakeHttpClient и RecordingSpanRecorder хранят каждый запрос и каждый спан, которые им передали. Им место в тестах, а не в воркере.

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

• Конфигурация — опции SDK и для чего каждая из них.

• Быстрый старт — первый запуск флоу по шагам.

• Вебхуки — приёмник доставок, которые присылает Slen.