Weave Code
Client Laravel Package
openai-php/client
OpenAI PHP is a community-maintained PHP client for the OpenAI API, giving Laravel and PHP applications typed, framework-agnostic access to chat, responses, embeddings, images, audio, files, and streaming, backed by an active community and thousands of GitHub stars.
⚡️ OpenAI PHP is a supercharged community-maintained PHP API client that allows you to interact with OpenAI API.
Frequently asked questions about Client
- How do I install openai-php/client in a Laravel application?
- Run composer require openai-php/client. The package needs a PSR-18 HTTP client, and Laravel already ships guzzlehttp/guzzle, so discovery normally resolves one automatically; if not, also require guzzlehttp/guzzle and php-http/discovery. No service provider registration is required because the package is framework-agnostic.
- Which PHP and Laravel versions does openai-php/client support?
- The package requires PHP 8.2 or newer. Because it is framework-agnostic, it works with any Laravel release running on that PHP version, including Laravel 10, 11 and 12. If your app is still pinned to PHP 8.1 or earlier, Composer will block the installation, so upgrade PHP first.
- How do I configure and bind the OpenAI client as a singleton in Laravel?
- Build the client once with OpenAI::factory()->withApiKey(config('services.openai.key'))->make() and bind it as a singleton in a service provider so the same HTTP client, base URI and headers are reused. Keep the key in config/services.php and .env rather than calling env() from application code. The factory also supports withBaseUri(), withOrganization(), withHttpHeader() and withHttpClient() for custom setups.
- How do I stream OpenAI responses in Laravel with openai-php/client?
- Call createStreamed() on the chat() or responses() resource and iterate the returned stream, forwarding each delta to your client. In Laravel you can return a streamed response or broadcast each chunk as an event so the real-time UI stays decoupled from the request cycle. Version 0.21.0 reduces stream processing overhead, which matters for long chat and assistant loops.
- Should I use chat() or responses() for a new Laravel chatbot or agent?
- The chat() resource wraps the widely supported Chat Completions endpoint and is fine for straightforward conversational features. The responses() resource targets OpenAI's newer Responses API and, as of v0.21.0, adds programmatic tool calling, the apply_patch tool, web search image results and more flexible retrieval settings. New agentic capabilities tend to land in responses() first, so prefer it for greenfield tool-heavy projects.
- How does openai-php/client handle tool calling and the apply_patch tool?
- Both chat() and responses() accept tool definitions, and v0.21.0 adds programmatic tool calling plus an apply_patch tool to the responses() endpoint. Treat model-emitted arguments as untrusted input: validate them against a strict schema and authorise the action before mutating state, ideally inside a queued job or event listener. Tool loops can multiply API calls quickly, so cap concurrency and add retry and backoff policies.
- Can I point openai-php/client at Azure OpenAI or a custom base URI?
- Yes. Use OpenAI::factory()->withBaseUri(...), withHttpHeader() for an api-key header and withQueryParams() for values such as api-version to target Azure OpenAI or any OpenAI-compatible gateway. You can also inject your own PSR-18 client preconfigured with middleware for logging, retries or proxies, which keeps multi-cloud deployments flexible.
- How do I test Laravel code that calls OpenAI without hitting the real API?
- Because the client depends on a PSR-18 HTTP client, inject a fake implementation via OpenAI::factory()->withHttpClient($fake)->make() and return canned JSON payloads in your tests. A mocking library such as Mockery or Guzzle's MockHandler lets you assert on the request body and headers too. Bind the client behind an interface or container key so feature tests can swap the fake without touching production code.
- How should I handle rate limits, retries and API errors in production?
- Failures throw OpenAI\Exceptions\ErrorException, which exposes getErrorMessage(), getErrorCode() and getErrorType(), while HTTP 429 signals rate limiting. Map these exceptions in Laravel's exception handler render() method for friendly responses, and move fine-tuning, batch work and long tool loops onto queues with throttling and exponential backoff. Log usage data such as usage->totalTokens, and account for the cache_write_tokens field added in v0.21.0, so cost dashboards stay accurate.
- Is openai-php/client actively maintained, and what are the Laravel-specific alternatives?
- It is a community-maintained package with an active release cadence, thousands of GitHub stars and regular endpoint coverage updates, which makes it a reasonable production dependency. If you want Laravel-native facades, config publishing and a ready-made service provider, the companion openai-php/laravel wrapper builds on this client. Other options include calling the API through Laravel's HTTP client directly, though you then lose the typed resources and streaming helpers.
Weaver
How can I help you explore Laravel packages today?