Use the SDK in a Laravel application

The PHP SDK comes with a service provider for Laravel. It reads the settings of the SDK from the environment of your application, builds one SDK from them and puts it into the container. Your code takes that SDK by type, or calls it through the Slen facade.

Set it up

Laravel finds the service provider and the facade of the package by itself, through package discovery, once the package is installed — Installation gives the command.

SLEN_API_KEY=sl_live_…

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

The config file

• A key reads the variable the table names. Without the variable it holds its default.

• The last column is the option of the SDK the key becomes — Configuration says what each is for.

• SLEN_LOG_CHANNEL names a channel of config/logging.php the journal of the SDK goes to. Without it the journal goes to the logger of your application — Logging.

• SLEN_SPANS=log writes the spans to the same logger, at the level SLEN_SPAN_LEVEL names. Any other value writes them nowhere. To send them somewhere else, bind your own recorder to Slen\Sdk\Observability\SpanRecorderInterface in the container — Spans.

• SLEN_WEBHOOK_SECRET is the signing secret the webhooks of the SDK check deliveries with — Webhooks.

• The values are checked when the SDK is first taken from the container: an empty key, or a timeout that is zero or not a number, throws InvalidArgumentException there.

Call Slen

The facade calls the SDK of the container. Every module of the SDK is a method of the facade.

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;

The SDK is one for the whole application. Any class the container builds — a controller, a job, a command — can take it by its type, Slen\Sdk\SlenSdk, in its constructor or in a method. Outside such a class, ask the container for it.

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;
}

The SDK keeps no static state, so it is safe in a worker that serves many requests — Run it under Octane.

In a test of your application, bind Slen\Sdk\SlenSdk to an SDK built on the test double of Testing your integration in place of the one the provider builds.

Run it under Octane

Under Laravel Octane — on FrankenPHP, RoadRunner or Swoole — a worker serves many requests one after another, and the SDK of the container can live as long as the worker.

• The SDK keeps no static state and does not change once it is built, so one request leaves nothing in it for the next.

• To write the journal of one request to a logger of its own, take a copy: SlenSdk::withLogger() returns a new SDK over the same HTTP client, and the SDK of the container keeps its logger — Logging.

• List SlenSdk and SlenConfig under warm in config/octane.php. The worker then builds the SDK when it starts, and its HTTP client keeps its connections open from one request to the next.

• A worker reads the config file once. After a change of the environment or of config/slen-sdk.php, reload the workers with php artisan octane:reload.

• Do not wait for a run inside a request: a wait sleeps in the worker for as long as the run takes. Send the run with operations.executeAsync(), and read the result from the execution.finished webhook or in a job of your queue — Async runs and waiting.

• Give a run inside a request a timeout and a number of repeats of its own, so that it does not outlast the request — Retries and timeouts.

• One SDK calls with one API key. An application that calls with several keys builds an SDK for each and keeps them in the container, not in a static property of its own.

• FakeHttpClient and RecordingSpanRecorder keep every request and every span they are given. They belong to tests, never to a worker.

Where to go next

• Configuration — the options of the SDK, and what each is for.

• Quickstart — the first run of a flow, step by step.

• Webhooks — a receiver of the deliveries Slen sends.