Configure the SDK

PHP

The options the SDK is built with, what each one is for, and the one environment variable it reads.

4 min read

The SDK is built once, with a few options, and every call uses them: the key, the timeouts and repeats of a request, the logger, where the spans go and the secret of your webhooks. This page lists the options and says what each one is for.

Build the 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 reads no environment variable: pass the key, as the example reads it from SLEN_API_KEY. It refuses an empty key, a timeout that is not above zero, a negative number of retries and a webhook tolerance below one second with InvalidArgumentException where the SDK is built, not on its first call. Building the SDK touches no network. The key and the webhook secret are not shown by a dump of the config or by a stack trace. In a Laravel application the service provider builds the SDK from the config file — Laravel integration.

The SDK of the example runs a flow like any other. Its logger prints a line only when a request is sent again or fails.

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;

The options

Option	Type	Default
`apiKey` required	`string`	none
`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`

The table prints a default as the language writes it: a time is in milliseconds in Node.js and in seconds in PHP.

The key — apiKey: an API key of your project, sl_live_…. Manage API keys shows where to issue one.
The timeouts — timeoutMs in Node.js; timeout and connectTimeout in PHP. They bound one attempt of a request — Retries and timeouts.
The repeats — retries: how many times a request is sent again after no answer, a 429 or a 503. 0 turns the repeats off — Retries and timeouts.
The journal — logger: where the SDK writes what it does — Logging.
The spans — spanRecorder, and in Node.js otlp as well — Spans.
The webhooks — webhookSecret and webhookToleranceSeconds: the signing secret of your endpoint, and how old a signature may be — Webhooks.

Three more parameters:

httpClient — the PSR-18 client the requests go through. It is used as it is, with its own timeouts. A test passes the double of Testing your integration here.
requestFactory, streamFactory — the PSR-17 factories the requests are made with.

Without them the SDK finds what your application has installed. When it finds Guzzle or Symfony HttpClient, it builds that client itself, with timeout and connectTimeout. Any other client keeps its own timeouts, and the SDK writes slen.config.timeout_not_applied to its journal.

A call takes what names its subject — the operation and its input, an id, an amount — and then one object of options: RequestOptions, or the options of that call, such as ExecuteOptions of a run. The options of a call that sends a request carry timeout and retries, which replace those of the config for that call alone — Retries and timeouts.

SlenConfig::withLogger(), SlenConfig::withSpanRecorder() and SlenConfig::withHttpClient() return a copy of the config with one thing changed. A built SDK does not change: SlenSdk::withLogger() returns a copy that writes its journal to another logger, over the same HTTP client — Logging.

Tests and a local stack

The SDK always calls the public API of Slen: the address is a constant of the SDK, and nothing in this reference passes it. Only a test or a local stack of Slen points the SDK at another address, with the option baseUrl — the host without /api, which the SDK adds itself. In a Laravel application such a test sets the configuration value slen-sdk.base_url; the config file of the package has no such key.

Where to go next

Retries and timeouts — what the SDK sends again by itself, and what each timeout bounds.
Logging — what the SDK writes to your logger.
Laravel integration — the SDK built from the config file of a Laravel application.
Testing your integration — an SDK that answers from a test double, without a network.

Built from openapi b070e1f, sdk contract 6a2e0e0, php 4089db3, node 0fa87be