Використовуйте 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.