Laravel Openai Laravel Package

Getting Started

The iteks/laravel-openai package is a thin Laravel integration around the openai-php/client SDK. It gives you a service-provider-registered client and a facade, so you avoid wiring up the OpenAI HTTP client yourself.

Install and configure

composer require iteks/laravel-openai
php artisan vendor:publish --tag=openai-config   # publishes config/openai.php

Add your credentials to .env:

OPENAI_API_KEY=sk-...
OPENAI_ORGANIZATION=org-...   # optional

Where to look first

1. config/openai.php — this is the only real configuration surface. It resolves the API key, organization, and (depending on version) base URI/timeouts.
2. The package's service provider — check how the client is bound into the container; that binding is what the facade resolves.
3. The OpenAI facade class — its docblock is the quickest map of exposed methods.

First use case — a basic chat completion:

use Iteks\OpenAI\Facades\OpenAI;

$response = OpenAI::chat()->create([
    'model' => 'gpt-4o-mini',
    'messages' => [
        ['role' => 'user', 'content' => 'Summarise this ticket in one line.'],
    ],
]);

return $response->choices[0]->message->content;

If you have Laravel 12, v1.0.6 is the release that adds compatibility — pin ^1.0.6 if you are on a fresh L12 install, otherwise the dependency constraint may refuse to install.

Implementation Patterns

Wrap it behind your own service. Don't call the facade directly from controllers. Create an App\Services\OpenAiService with your domain-specific methods (summariseTicket(), classifyLead(), embedDocument()) and let that class depend on the client. This keeps prompts testable and makes it trivial to swap providers later.

Inject the client, not the facade. The facade is a static proxy over the container binding. For anything you want to unit test, type-hint the client or your own service and resolve it from the container:

public function __construct(private OpenAiService $openAi) {}

Queue anything non-trivial. Chat completions are slow (seconds, not milliseconds) and costly. Dispatch a job, persist the response, and notify the user when done. A ProcessAiRequest job with $tries = 3 and a backoff() covering rate-limit spikes is the standard shape.

Persist prompt + response pairs. Store the model, parameters, token counts, and raw response for every call. You will need this for cost attribution, debugging hallucination reports, and reproducing regressions when you change a prompt.

Centralise model and parameter choices. Put model names, temperature, and token limits in a config or enum rather than scattering string literals. Model deprecations are frequent — you want a single place to change gpt-4o → whatever replaces it.

Use it inside existing pipelines. The common integration points are: an artisan command for batch backfills, a queued listener reacting to domain events (e.g. TicketCreated), and a scheduled task for embedding refreshes.

Gotchas and Tips

The package is thin — most issues are the OpenAI API, not the wrapper. Timeouts, 429 rate limits, and model-not-found errors surface essentially unchanged. Handle them at the boundary of your own service: catch OpenAI\Exceptions\ErrorException, log the request id, and rethrow something your app understands.

Config caching catches people out. OPENAI_API_KEY read once at config:cache time won't pick up runtime env changes. If you're toggling keys per-tenant, don't rely on the config file — resolve clients dynamically or clear the cache.

Facade in tests. The OpenAI facade isn't mockable the same way as a Laravel-native facade unless the package defines a fake helper. Prefer dependency injection so you can swap in a fake client in tests/. If you must test through the facade, use Http::fake() against the underlying HTTP layer (the SDK ultimately uses Guzzle, so Http::fake() may not intercept — check whether the package/client supports it, and fall back to a real fake client implementation).

Token accounting is your responsibility. The response object includes usage, but nothing aggregates it. Log it per call and roll it up; bills from OpenAI are per-project, not per-feature.

Streaming bypasses the normal response flow. If you stream a completion to a controller response, you lose the usage block and error handling gets awkward mid-stream. Prefer buffering unless the UX genuinely needs streaming.

Version constraint matters on fresh installs. v1.0.6 adds Laravel 12 support. If you are on Laravel 12 and Composer resolves something older, it will fail on framework conflicts — confirm the installed version with composer show iteks/laravel-openai.

Extension point is the container binding. The client is bound as a singleton; if you need a customised HTTP client (proxy, retry middleware, custom base URI for Azure/OpenAI-compatible endpoints like Ollama or vLLM), rebind it in a service provider after the package's provider registers.

Upgrade cadence. This is a low-activity, community-maintained package with a small surface area. That's a strength for stability, but it means you should track upstream openai-php/client releases yourself — new API features (structured outputs, new model families) arrive there first and may not be reflected in the facade's typed methods. The client is reachable, so you're not blocked.