README

A lightweight, underrated PSR-17/PSR-18 client for the current OpenAI API, with examples for every exposed SDK method, SSE streaming, streamed multipart uploads, structured errors, project scoping, and webhook signature verification.

Requirements

• PHP 8.1 or newer. CI tests PHP 8.1, 8.2, 8.3, 8.4, and 8.5.
• A PSR-17 request, stream, and URI factory.
• A PSR-18 HTTP client.
• The JSON extension.

Guzzle is used below because it provides both the PSR-17 factories and PSR-18 client implementation. The SDK itself depends only on the PSR interfaces, so other compliant implementations remain supported.

Installation

composer require softcreatr/php-openai-sdk guzzlehttp/guzzle

Client Setup

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use SoftCreatR\OpenAI\OpenAI;

$factory = new HttpFactory();
$openAI = new OpenAI(
    requestFactory: $factory,
    streamFactory: $factory,
    uriFactory: $factory,
    httpClient: new Client(['stream' => true]),
    apiKey: (string) getenv('OPENAI_API_KEY'),
    organization: (string) getenv('OPENAI_ORGANIZATION_ID'),
    project: (string) getenv('OPENAI_PROJECT_ID'),
);

Keep API keys on the server and out of source control. Organization and project IDs are optional.

Responses API

The Responses API is the recommended interface for new text and agentic integrations.

use const JSON_THROW_ON_ERROR;

$response = $openAI->createResponse([
    'model' => 'gpt-5.4-mini',
    'input' => 'Give me a one-sentence summary of PSR-18.',
]);

$result = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR);
echo $result['output'][0]['content'][0]['text'];

Endpoint methods return a PSR-7 ResponseInterface. Streaming calls return null after delivering their events to the callback.

Arguments

Body-only endpoints use a single body array:

$openAI->createEmbedding([
    'model' => 'text-embedding-3-small',
    'input' => 'A sentence to embed.',
]);

For endpoints with path parameters, a single combined array is the preferred v4 form. Path fields are separated from the request body using the endpoint template:

$openAI->updateConversation([
    'conversation_id' => 'conv_abc123',
    'metadata' => ['customer' => 'acme'],
]);

The v3 two-array form remains supported for existing integrations:

$openAI->updateConversation(
    ['conversation_id' => 'conv_abc123'],
    ['metadata' => ['customer' => 'acme']],
);

For GET and DELETE methods, non-path values become RFC 3986 query parameters. Path parameter values are URL encoded. The explicit form is available when method names are determined at runtime:

$response = $openAI->request(
    'listFiles',
    ['limit' => 20, 'after' => 'file_abc123'],
    customHeaders: ['X-Trace-Id' => 'trace_abc123'],
);

Streaming

Set stream to true and pass a callback. The decoder supports arbitrarily split chunks, CRLF and LF delimiters, comments, multiline data fields, final unterminated frames, and [DONE].

$openAI->createResponse(
    [
        'model' => 'gpt-5.4-mini',
        'input' => 'Write a short haiku about PHP.',
        'stream' => true,
    ],
    static function (array $event): void {
        if ($event['type'] === 'response.output_text.delta') {
            echo $event['delta'];
        }
    },
);

An ordinary JSON response is still returned when a callback is supplied without requesting an SSE stream.

File Uploads

Multipart endpoints accept readable local file paths. Files are copied as raw bytes into a temporary stream rather than being base64 encoded or assembled in one large PHP string.

$response = $openAI->uploadFile([
    'file' => __DIR__ . '/data.jsonl',
    'purpose' => 'user_data',
]);

Repeated upload fields such as image inputs and skill files accept arrays of paths. Nested non-file values are encoded using bracket notation.

Errors

4xx and 5xx responses throw OpenAIException. The exception keeps the parsed API error, raw response body, response headers, status code, and x-request-id for diagnostics.

use SoftCreatR\OpenAI\Exception\OpenAIException;

try {
    $openAI->retrieveModel(['model' => 'missing-model']);
} catch (OpenAIException $exception) {
    error_log(sprintf(
        'OpenAI request %s failed (%d): %s',
        $exception->getRequestId() ?? 'unknown',
        $exception->getCode(),
        $exception->getMessage(),
    ));
}

PSR-18 transport failures are wrapped in OpenAIException and retain the original exception as getPrevious().

Webhooks

Verify the signature against the exact raw request body before decoding or changing it. The verifier follows OpenAI's webhook guide and supports multiple v1 signatures during secret rotation.

use SoftCreatR\OpenAI\Webhook\WebhookVerifier;

$rawBody = (string) $request->getBody();
$event = (new WebhookVerifier((string) getenv('OPENAI_WEBHOOK_SECRET')))
    ->unwrap($rawBody, $request->getHeaders());

if ($event['type'] === 'response.completed') {
    // Handle the completed response idempotently.
}

The default replay tolerance is 300 seconds. Invalid signatures throw InvalidWebhookSignatureException; valid signatures with invalid JSON throw WebhookException.

Examples

Examples load the ignored project-level .env through examples/OpenAIFactory.php:

cp .env.example .env
php examples/responses/createResponse.php

Set OPENAI_ADMIN_KEY only when running examples under examples/administration.

Supported Methods

The catalog follows the current OpenAI API reference. Fine-tuning is retained for transitional compatibility and is marked deprecated. APIs that OpenAI classifies as legacy or has scheduled for shutdown are intentionally absent.

Administration

Audio

Batches

Chat

Chatkit

Containers

Conversations

Embeddings

Files

Fine Tuning

Images

Models

Moderations

Realtime

Responses

Skills

Uploads

Vector Stores

Custom API Origin

origin accepts either a hostname or an absolute base URL. A hostname uses /v1; an absolute URL keeps its path unless basePath is supplied explicitly.

$openAI = new OpenAI(
    requestFactory: $factory,
    streamFactory: $factory,
    uriFactory: $factory,
    httpClient: new Client(['stream' => true]),
    apiKey: (string) getenv('OPENAI_API_KEY'),
    origin: 'https://gateway.example/openai/v1',
);

Deprecated And Removed APIs

Version 4 deliberately does not expose APIs that OpenAI classifies as legacy, has already removed, or has scheduled for shutdown: classic Completions, Assistants/Threads/Runs/Messages, Realtime Beta session creation, Evals, Videos, and DALL-E image variations. Use Responses and Conversations instead of Assistants.

The self-serve fine-tuning routes remain temporarily available and are marked deprecated because eligible existing customers can still use them during OpenAI's transition. See OpenAI's deprecation schedule and the v4 migration notes before upgrading.

Development

composer test
composer analyse
vendor/bin/php-cs-fixer fix --dry-run --diff
composer audit

License

ISC