Client Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require openai-php/client
   

   Add to config/services.php (if not using Laravel's default OpenAI config):

   'openai' => [
       'api_key' => env('OPENAI_API_KEY'),
       'base_uri' => env('OPENAI_BASE_URI', 'https://api.openai.com/v1'),
   ],
   

2. First Use Case: Generate a chat completion in a Laravel controller:

   use OpenAI\Laravel\Facades\OpenAI;
   
   public function askChatGPT(Request $request) {
       $response = OpenAI::chat()->create([
           'model' => 'gpt-4',
           'messages' => [
               ['role' => 'user', 'content' => $request->input('prompt')],
           ],
       ]);
       return response()->json($response->choices[0]->message->content);
   }
   

3. Key Starting Points:

   • Official Documentation
   • vendor/openai-php/client/docs/ (local API reference)
   • php artisan vendor:publish --provider="OpenAI\Laravel\OpenAIServiceProvider" (publish config)

Implementation Patterns

Core Workflows

1. Model Selection & Caching:

   // Cache model responses (e.g., for rate-limiting)
   $response = OpenAI::cache()->remember('gpt-4-prompt-123', now()->addHours(1), function () {
       return OpenAI::chat()->create([...]);
   });
   

2. Streaming Responses:

   $response = OpenAI::chat()->create([
       'model' => 'gpt-3.5-turbo',
       'stream' => true,
       'messages' => [...],
   ]);
   
   foreach ($response->choices as $choice) {
       echo $choice->delta->content;
   }
   

3. Modular Services: Create a dedicated service class:

   class AIAssistantService {
       public function __construct(private OpenAIClient $client) {}
   
       public function generateSummary(string $text): string {
           $response = $this->client->chat()->create([
               'model' => 'gpt-3.5-turbo',
               'messages' => [
                   ['role' => 'system', 'content' => 'Summarize the following text concisely.'],
                   ['role' => 'user', 'content' => $text],
               ],
           ]);
           return $response->choices[0]->message->content;
       }
   }
   

Integration Tips

• Laravel Events: Trigger AI actions on model events (e.g., created:post):

  Event::listen('created:post', function (Post $post) {
      OpenAI::chat()->create([
          'model' => 'gpt-3.5-turbo',
          'messages' => [
              ['role' => 'user', 'content' => "Generate a SEO title for: {$post->title}"],
          ],
      ]);
  });
  

• Queue Jobs: Offload expensive calls to queues:

  class GenerateAIResponseJob implements ShouldQueue {
      public function handle() {
          OpenAI::chat()->create([...]);
      }
  }
  

• API Rate Limiting: Use Laravel's throttle middleware for API key protection:

  Route::middleware(['throttle:100,1'])->group(function () {
      Route::post('/ai', [AIController::class, 'ask']);
  });
  

Gotchas and Tips

Common Pitfalls

1. API Key Exposure:

   • Never hardcode keys. Use Laravel's .env and env() helper.
   • Restrict API keys to specific IPs in OpenAI dashboard if possible.

2. Rate Limits:

   • Default limits: 3 requests/second for gpt-3.5-turbo, 1 request/second for gpt-4.
   • Monitor usage via OpenAI Dashboard.
   • Implement exponential backoff for retries:

     try {
         $response = OpenAI::chat()->create([...]);
     } catch (RateLimitException $e) {
         sleep($e->retryAfter);
         retry();
     }
     

3. Token Limits:

   • gpt-3.5-turbo: 4,096 tokens (input + output).
   • gpt-4: 8,192 tokens.
   • Use OpenAI::moderation()->create() to check content before sending.

4. Streaming Quirks:

   • Streams may truncate if not processed immediately. Buffer responses:

     $buffer = '';
     foreach ($response->choices as $choice) {
         $buffer .= $choice->delta->content;
     }
     

Debugging Tips

• Enable Verbose Logging:

  OpenAI::setApiKey('...', [
      'verbose' => true,
      'debug' => true,
  ]);
  

  Check logs for raw API requests/responses.

• Mocking for Tests: Use Mockery or Venture to stub OpenAI calls:

  $mock = Mockery::mock(OpenAIClient::class);
  $mock->shouldReceive('chat->create')
       ->once()
       ->andReturn(new ChatCompletion('mocked response'));
  $this->app->instance(OpenAIClient::class, $mock);
  

Extension Points

1. Custom Models: Extend the client for internal models:

   class CustomOpenAIClient extends OpenAIClient {
       public function customModel() {
           return new CustomModel($this->getHttpClient());
       }
   }
   

2. Middleware: Add request/response middleware:

   OpenAI::extend(function ($client) {
       $client->getHttpClient()->getMiddleware()->push(
           new AddHeadersMiddleware(['X-Custom-Header' => 'value'])
       );
   });
   

3. Response Transformers: Decorate responses for consistency:

   OpenAI::extend(function ($client) {
       $client->setResponseTransformer(function ($response) {
           return json_decode($response->getBody(), true);
       });
   });
   

4. Laravel Service Provider: Bind custom configurations:

   public function boot() {
       OpenAI::setApiKey(config('services.openai.custom_key'));
       OpenAI::setBaseUri(config('services.openai.custom_uri'));
   }
   

Performance Optimizations

• Batch Processing: Use files endpoint for bulk operations (e.g., fine-tuning):

  $response = OpenAI::files()->create([
      'purpose' => 'fine-tune',
      'file' => fopen('data.jsonl', 'r'),
  ]);
  

• Caching Strategies: Cache responses by:

  • Model + prompt hash (for deterministic outputs).
  • User ID + context (for personalized responses).

  Cache::remember("ai_{$userId}_{$promptHash}", now()->addMinutes(5), function () use ($prompt) {
      return OpenAI::chat()->create([...]);
  });