openai-php/client: a PHP client for the OpenAI API

What openai-php/client is for

The package is a PHP API client for the OpenAI API, described in its README as "a community-maintained PHP API client that allows you to interact with the Open AI API." That sentence is the whole scope. It does not host models, proxy requests, or add caching. It turns HTTP calls into PHP method calls and turns JSON responses into objects you can read with property access.

The audience is narrow and specific. You need PHP 8.2 or newer, Composer, and a codebase that already talks to external HTTP services. If you are building a Laravel or Symfony application and want to call the Responses, Chat, Audio, Embeddings, Files, or Vector Stores endpoints without writing a curl wrapper, this is the layer that saves you that work. If your application is in Python, Node, or Go, nothing here applies.

One naming detail is worth stating plainly. The vendor prefix is openai-php, and the Composer package is openai-php/client. That matters because the related search data around the word "client" is mostly about unrelated things: Minecraft client mods, client portals, client versus customer. None of that describes this package. The repository topics (api, client, gpt-3, gpt-4, gpt-5, language, natural, openai, php, processing, sdk) are a better guide to what it actually is.

How the client is structured

The README's table of contents is the clearest map of the architecture. The client exposes named resources, and each resource groups the endpoints for one part of the OpenAI API: Models, Responses, Conversations, Conversations Items, Containers, Containers Files, Chat, Audio, Embeddings, Files, FineTuning, Moderations, Images, Vector Stores, Vector Stores Files, Vector Stores File Batches, Batches, and Realtime Ephemeral Keys.

Several entries are marked as legacy or deprecated in that same table: Completions (legacy), Assistants, Threads, Thread Messages, Thread Runs, Thread Run Steps, FineTunes, and Edits. The README labels them rather than removing them, which tells you the maintainers keep old surface area around for existing users instead of deleting it. If you are starting fresh, the non-deprecated resources are the ones to read first.

Responses are returned as objects with typed properties. The Models resource example shows `$response->object` returning 'list', iterating `$response->data`, and reading `$result->id` and `$result->object`. Every response also exposes `toArray()`, which returns the underlying array. That dual interface is the practical detail: you can use property access for readability and drop to `toArray()` when you need to pass the payload somewhere else.

Authentication is handled at construction. The factory example shows `withApiKey`, `withOrganization`, `withProject`, `withBaseUri`, `withHttpClient`, `withHttpHeader`, `withQueryParam`, and `withStreamHandler`. The base URI defaults to api.openai.com/v1 and can be pointed elsewhere, which is the hook for compatible endpoints. The HTTP client defaults to whatever PSR-18 discovery finds, and `withStreamHandler` is described in the README as the way to provide a custom stream handler for streaming responses.

Installing openai-php/client and making a first call

Installation goes through Composer. The README states the requirement as PHP 8.2+, then gives the package name.

composer require openai-php/client

The README adds a second step that is easy to miss: the `php-http/discovery` Composer plugin must be allowed to run, or you install a client manually if your project has no PSR-18 client. The fallback it names is Guzzle.

composer require guzzlehttp/guzzle

With the package present, the README's first example builds a client from an environment variable and calls the Responses resource.

$yourApiKey = getenv('YOUR_API_KEY');
$client = OpenAI::client($yourApiKey);

$response = $client->responses()->create([
    'model' => 'gpt-4o',
    'input' => 'Hello!',
]);

echo $response->outputText; // Hello! How can I assist you today?

The comment in the README shows what a successful call prints: the model's reply text, read through the `outputText` property. If nothing prints, check that `YOUR_API_KEY` is actually set in the environment the PHP process sees, because `getenv` returns false when the variable is missing and the client is constructed with that value.

When you need per-project settings, the factory replaces the shorthand. The README's example chains `withApiKey`, `withOrganization`, `withProject`, `withBaseUri`, and `withHttpClient` before calling `make()`.

$yourApiKey = getenv('YOUR_API_KEY');

$client = OpenAI::factory()
    ->withApiKey($yourApiKey)
    ->withOrganization('your-organization') // default: null
    ->withProject('Your Project') // default: null
    ->withBaseUri('openai.example.com/v1') // default: api.openai.com/v1
    ->withHttpClient($httpClient = new \GuzzleHttp\Client([]))
    ->make();

Note the base URI in that snippet has no scheme. The README writes it as `openai.example.com/v1`, so copy it exactly as shown when you adapt the example rather than assuming it is a full URL.

Where openai-php/client will not help you

The package is a client, not a platform. It does not manage API keys, retry failed requests, or store responses. The README documents `withStreamHandler` for streaming, but it does not document rollback, retry policy, or rate-limit handling, so you should treat those as your application's responsibility.

The PHP 8.2 floor is a real constraint. On PHP 8.1 or older, Composer will refuse the install, and there is no version of the package documented for those runtimes. If you maintain a legacy application you cannot upgrade, this client is the wrong tool.

The deprecated resources are a second boundary. Assistants, Threads, and the other entries marked deprecated in the README still exist, but building new features on them means building on surface area the project has already flagged. The README does not say when or whether they will be removed, so the safe reading is that new work belongs on the current resources.

Finally, the client assumes you can reach the OpenAI API from your server. If your deployment has no outbound network access, or if your organisation routes all model traffic through a gateway with a different contract, you will spend your time on the `withBaseUri` and `withHttpClient` hooks rather than on the resource methods.

openai-php/client compared with calling the API directly

The obvious alternative is writing your own HTTP calls with Guzzle or another PSR-18 client. The difference is what you own. With raw HTTP you control every header, every retry, and every timeout, and you carry no dependency beyond the HTTP client itself. You also write the request bodies and parse the responses yourself, for every endpoint you use.

openai-php/client inverts that. You get named resources, typed response objects, and `toArray()` when you need the raw payload. The cost is a dependency that must track the OpenAI API as it changes, and a release cycle you do not control. The repository's recent releases show that cycle: v0.19.2 on 2026-04-19, v0.20.0 on 2026-06-13, and v0.20.1 on 2026-07-20, with the last push to the repository on 2026-09-11. The version numbers are still below 1.0, which is worth knowing before you pin it in a long-lived project.

The second alternative is the official OpenAI SDKs. The README does not compare itself to them, and this package is explicitly community-maintained rather than an OpenAI product. If your team already standardises on an official SDK in another language, adding a PHP client maintained by a different group is a second maintenance relationship to track.

Licence, maintenance and upgrade cost

The repository is licensed under MIT, and the README links a license badge pointing at the same identifier. MIT is permissive: you can use the package in closed-source and commercial applications, and you keep the copyright notice and licence text with the distribution. That is the general shape of the licence, not legal advice for your situation.

The project is not archived, and the last push was on 2026-09-11, so the repository is being touched. The README also carries a sponsorship section naming Nuno Maduro, Sandro Gehri, and Connor Tumbleson, and asks that businesses relying on the package support the maintainers. That is a fair signal about how the work is funded: it is community effort, not a vendor with a support contract.

Upgrade cost is mostly version discipline. The releases are 0.x, and the README already labels a long list of resources as legacy or deprecated. Before upgrading, read CHANGELOG.md in the repository, which is the file the project keeps for exactly this purpose. The README itself does not document a migration path between minor versions.

Editorial conclusion

Adopt openai-php/client if you have a PHP 8.2+ codebase and want typed access to the OpenAI API without hand-writing HTTP calls. Skip it if your stack is not PHP, or if you need a client that ships its own HTTP transport, since the documentation expects you to provide a PSR-18 client such as Guzzle. Before writing production code, verify which resources your account can reach, confirm the exact package version you install with Composer, and read the sections marked deprecated in the README so you do not build on a resource the project has already retired.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. openai-php/client on GitHub
4. README
5. Releases