openai-php/laravel: the OpenAI PHP client as a Laravel package

What openai-php/laravel actually is, and who it is for

This repository holds the Laravel integration code for OpenAI PHP, not the client itself. The README states that plainly: the framework-agnostic client lives in the openai-php/client repository, and if you want to use OpenAI PHP outside Laravel you should go there instead. So the audience is narrow and specific. You are building or maintaining a Laravel application on PHP 8.2 or newer, you want to call the OpenAI API from PHP, and you would rather not hand-roll an HTTP layer, a service binding and a test double. The package gives you a facade, a config file and a fake() method, and it is community-maintained rather than an official OpenAI SDK. That last point matters when you weigh support expectations. The README asks users and businesses that rely on the package to sponsor the two named maintainers, which is a fair signal of how the project is funded. The last push to the repository was on 2026-09-17, the same day v0.21.0 was released, so the code is current as of that date.

The facade, the config file and the client underneath

The architecture is thin by design. Composer pulls in the integration package, which in turn depends on the framework-agnostic client. A Laravel service provider registers the client in the container, and the OpenAI facade resolves it. Configuration is read from config/openai.php, which is populated from environment variables: OPENAI_API_KEY, OPENAI_ORGANIZATION, OPENAI_PROJECT, OPENAI_BASE_URL and OPENAI_REQUEST_TIMEOUT. The base URL defaults to api.openai.com/v1 and the request timeout defaults to 30 seconds, according to the README. Because the facade is a container binding, anything you would normally do with Laravel's container applies: swap the binding in a test, resolve it in a queued job, or inject it into a constructor. The package does not add a queue, a retry policy or a caching layer. If you want those, they are yours to build on top of the client, and the README does not document any of them. That is a deliberate scope decision, and it is the main reason the package stays small enough to reason about.

Installing openai-php/laravel and making a first call

Installation assumes Composer and PHP 8.2 or later. The README gives two commands. The first pulls the package in; the second runs the package's own install command, which creates config/openai.php and appends blank OPENAI_API_KEY and OPENAI_ORGANIZATION entries to your .env file.

composer require openai-php/laravel
php artisan openai:install

After that, open .env and fill in the key. The README shows the shape of the values, with the sk- and org- prefixes:

OPENAI_API_KEY=sk-...
OPENAI_ORGANIZATION=org-...

With the key in place, the facade is ready. The README's example calls the responses resource and reads outputText off the returned object:

use OpenAI\Laravel\Facades\OpenAI;

$response = OpenAI::responses()->create([
    'model' => 'gpt-5',
    'input' => 'Hello!',
]);

echo $response->outputText;

If you see the model's reply printed, the wiring is correct. If you get an authentication error instead, the key in .env is the first thing to check, followed by whether config caching is serving a stale config/openai.php. The README does not document a config:clear step for this package, but that is standard Laravel behaviour rather than something the package controls.

Faking the API in tests is the strongest reason to pick this over raw HTTP

The testing story is where the Laravel wrapper earns its place. OpenAI::fake() takes an array of pre-built response objects, and the README states that fakes are returned in the order they are provided. Response classes expose their own fake() constructor, so you build a realistic object by passing only the fields your assertion needs. The README's example builds a CreateResponse with a single choices entry.

use OpenAI\Laravel\Facades\OpenAI;
use OpenAI\Responses\Responses\CreateResponse;

OpenAI::fake([
    CreateResponse::fake([
        'choices' => [
            [
                'text' => 'awesome!',
            ],
        ],
    ]),
]);

Assertions come next. The README shows assertSent with a resource class and a closure that receives the method name and the parameters array, which lets you check both which endpoint was hit and what was sent to it. In the README's own example the closure checks the model and the prompt. That combination, deterministic responses plus request assertions, is what keeps an OpenAI-backed feature inside a normal PHPUnit or Pest suite without network calls. Note the ordering contract: if a code path makes two calls, your fake array must match that order, and the README does not describe a fallback for unmatched calls.

Where this package stops being the right tool

Three limits are visible from the repository itself. First, it is Laravel-only by construction. The README points framework-agnostic users at openai-php/client, and there is no documented path to use this package inside Symfony, a plain PHP script or a non-Laravel microservice. Second, the version numbers are still pre-1.0. The recent releases run v0.19.1, v0.20.0 and v0.21.0, with v0.21.0 published on 2026-09-17. Semver below 1.0 permits breaking changes in minor releases, so an upgrade from v0.19 to v0.21 deserves a read of the CHANGELOG rather than a blind composer update. Third, the package is a client, not an orchestration layer. There is no documented retry, backoff, rate-limit handling, streaming helper or cost tracking. If your workload needs durable job retries around model calls, you are composing that yourself with Laravel's queue and the client's exceptions. The README also does not document rollback or downgrade steps, so pinning a version in composer.json before you upgrade is the practical precaution.

How it differs from calling the OpenAI API with Laravel's HTTP client

The honest alternative is not another package, it is Laravel's own Http facade. With Http::withToken(config('services.openai.key'))->post('https://api.openai.com/v1/responses', ...) you get a request, a response, and nothing else. You write the URL, the JSON body and the error handling, and you get no typed response objects. openai-php/laravel instead gives you resource methods such as responses()->create(), typed response classes with named properties like outputText, and the fake/assertSent pair for tests. The trade is abstraction for control. The raw HTTP approach never lags behind a new API endpoint, because you are writing the endpoint yourself; the client package has to add support for it and ship a release. If you are calling one endpoint occasionally, the Http facade is fewer moving parts. If you are calling several resources across a codebase and want tests that do not touch the network, the typed client is the better fit. The README does not compare the two, which is why it is worth deciding this before you install anything.

Licence, maintenance and the cost of upgrading

The package is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are retained. That is the whole of the licence implication here; anything beyond it is a question for your own legal review, not something the README settles. Maintenance is community-driven, with the README naming Nuno Maduro and Sandro Gehri as the maintainers to sponsor. The repository is not archived, and the last push was on 2026-09-17, so it is not abandoned. The upgrade cost is the part teams underestimate. Because the package tracks the OpenAI API surface, each minor release can add resources and change response shapes, and the pre-1.0 versioning means that can happen without a major bump. Practically, that means reading CHANGELOG.md before each composer update, pinning an exact version in composer.json for production, and checking that your config/openai.php still matches the keys the installed version expects after the update.

Editorial conclusion

Adopt openai-php/laravel if your application is Laravel and you want OpenAI calls behind a facade you can fake in tests; skip it if you need a framework-agnostic client, since that is a separate repository, or if you cannot run PHP 8.2. Before wiring it into production, verify the config/openai.php keys your deployment reads, confirm how OPENAI_BASE_URL and OPENAI_REQUEST_TIMEOUT are set in each environment, and check the CHANGELOG for the breaking changes between v0.19.1 and v0.21.0, because the package is still below 1.0.

Frequently asked questions

Official sources

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