Add configurable HTTP Handler for logging, retries, and custom headers

[saeedhosan]

What: Add Configurable HTTP Handler for Logging, Retries, and Custom Headers

• [ ] Bug Fix
• [x] New Feature
• [ ] Docs

Description:

This pull request adds a configurable HTTP handler for logging, retries, custom headers, and more. Instead of relying on a third-party HTTP bridge client, most features can be achieved using the HTTP handler itself.

Starter documentation - The starter documentation

Why this to be useful

• Introduces configurable HTTP handler, allowing to interect with requests/responses using guzzle middleware
• Automatically capture Laravel HTT events which helps to logging for tools like Telescope , Pulse and others
• This enables basic to advance uses with handler and middleware for logging retry, with header and much more

What was changed

• Added http_handler option to config/openai.php, allowing developers to define custom handler class-string.
• Updated the internal ServiceProvider for HTTP client to dynamically resolve the handler using:

use OpenAI\Laravel\Http\Handler;

->withHttpClient(new \GuzzleHttp\Client([
         //...
         'handler' => Handler::resolve(config('openai.http_handler'))
 ]));

Related:

The previous PR : https://github.com/openai-php/laravel/pull/172

https://github.com/openai-php/laravel/issues/75 https://github.com/openai-php/laravel/pull/127 https://github.com/openai-php/laravel/pull/78

[iBotPeaches]

I understand this is a highly requested feature so at some point we need to bite bullet and do something. Between the various attempts of a PSR-18 complaint integration and this - what led you to this method? It seems we have more to manage with event emission vs like a tiny PSR-18 bridge - https://github.com/openai-php/laravel/pull/127#issuecomment-2786757129

Trying to understand pro/con.

[saeedhosan]

Thanks for the follow-up question!

The PSR-18 bridge like laravel-http-psr18 does dispatch Laravel HTTP events, but it’s less flexible when developers want to extend behavior — for example, adding retry request, custom headers, or logging through Laravel’s familiar interfaces.

In this package, the http client is created internally in the ServiceProvider and using just like (e.g., OpenAI::chat()) to maintain the zero-config experience developers expect. The configurable handler lets developers to apply their own logic using custom handler if they want to interact with HTTP request/response handling — for instance, custom middleware, retry request, or custom headers manipulation — without needing to create a new http client instance.

Maintenance: The handler itself is intentionally small and leverages Guzzle’s native middleware. This keeps maintenance minimal while allowing advanced developer to hook in their own behaviors.

In short, the handler approach provides first-class integration with the HTTP client ecosystem (Laravel Http events , request retries , custom headers via middleware) while keeping configuration optional and dependency-free.