PHP

The PHP SDK publishes to Packagist, which serves Composer. It requires PHP 8.2 or later with the curl extension, and nothing from Composer at runtime.

Install

composer require your-org-api/sdk

Options

Set these for PHP in SDK Studio. Each one names its key for octri sdk settings set. Every option, for every language, is in the settings reference.

Client stylechoicedefault: class

class gives callers a client to create. functions gives free functions to import. See client style.

clientStyleByLang.php

Namespacechoicedefault: tags

Groups operations by tags, by URL path, or not at all with none.

namespaceByLang.php

Method namingchoicedefault: short

short drops the group's word from the method name, and full keeps the operation ID. Set for every language at once.

methodNaming

Argument stylechoicedefault: positional

object takes one parameters object, and positional takes arguments in order. See argument style.

outputByLang.php.argumentStyle

Doc commentschoicedefault: full

full or minimal.

outputByLang.php.docComments

Usage examplechoicedefault: full

full or concise.

outputByLang.php.usageExample

File headerchoicedefault: include

include or omit. Omitting it needs the Enterprise plan. Set for every language at once.

fileHeader

Package name

Packagist names are always vendor/package. The generator derives the vendor from your package name and uses sdk as the package, and the PHP namespace follows the same name in snake case:

acme-api/sdk      Composer name (composer require acme-api/sdk)
acme_api          PHP namespace

The vendor segment is claimed on Packagist by whoever registers first, so register yours before you need it.

Packagist reads from your repository

This is the part that surprises people coming from npm.

Packagist doesn't host your code, it points at your repo

Composer resolves packages from Packagist, but Packagist stores only metadata and fetches the code from the git repository and its tags. A release is a tag in your repo, and Packagist picks it up via a webhook.

That means the PHP Repository isn't optional decoration: without it there's nothing for Packagist to read. Set it per language. See Publishing.

What callers write

<?php

use acme_api\Acme;
use acme_api\ClientAuthConfig;
use acme_api\ClientConfig;

$config = new ClientConfig();
$config->baseUrl = 'https://api.acme.com/v1';
$auth = new ClientAuthConfig();
$auth->bearer = getenv('ACME_TOKEN') ?: null;
$config->auth = $auth;

$acme = new Acme($config);

// listPaginated returns a lazy Generator: foreach pulls one page at a time.
foreach ($acme->users->listPaginated(limit: 100) as $user) {
    echo $user->id, PHP_EOL;
}

Parameters are named arguments. list is a reserved word in PHP, so a plain list operation is generated as list_() beside its listPaginated() companion. Failures throw a subclass of SdkHttpError per common status (SdkNotFoundError, SdkRateLimitError and so on), each carrying statusCode and requestId.

Runtime


Requires	PHP 8.2 or newer
HTTP	cURL
Timeout	30 seconds per attempt
Retries	Up to 3 attempts, with backoff from 500 ms to 8 seconds
Idempotency keys	`POST` and `PATCH`

Those are the defaults. See every setting and retries and timeouts to change them.

Streaming

For an operation that streams:

foreach ($client->events->stream() as $event) {
    echo $event->id;
}

Returns a Generator. See streaming.

Handling errors

try {
    $client->users->get(id: "usr_1");
} catch (SdkNotFoundError $error) {
    return null;
} catch (SdkHttpError $error) {
    error_log($error->statusCode . " " . $error->requestId);
    throw $error;
}

Each common status has its own subclass of SdkHttpError. $error->data holds the decoded model, which you can narrow with instanceof. See what's in the package.

Publishing

Connect Packagist and set the repository.

Client shape

What these options do across languages.