Laravel Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require openai-php/laravel
   

2. Run the installer (creates config/openai.php and updates .env):

   php artisan openai:install
   

3. Configure .env with your OpenAI credentials:

   OPENAI_API_KEY=sk-your-key
   OPENAI_ORGANIZATION=org-your-org
   

4. First API call (using the responses facade):

   use OpenAI\Laravel\Facades\OpenAI;
   
   $response = OpenAI::responses()->create([
       'model' => 'gpt-3.5-turbo',
       'messages' => [['role' => 'user', 'content' => 'Hello!']],
   ]);
   echo $response->choices[0]->message->content;
   

Where to Look First

• Facade methods: OpenAI::responses(), OpenAI::chat(), OpenAI::completions(), etc.
• Configuration: config/openai.php (timeout, base URL, etc.)
• Testing: OpenAI::fake() for mocking responses.

Implementation Patterns

Core Workflows

1. Chat Completions (Most Common Use Case)

// Single request
$response = OpenAI::chat()->create([
    'model' => 'gpt-4',
    'messages' => [
        ['role' => 'system', 'content' => 'You are a helpful assistant.'],
        ['role' => 'user', 'content' => 'Explain Laravel middleware.'],
    ],
]);

// Streamed response (for real-time UX)
$response = OpenAI::chat()->create([
    'model' => 'gpt-3.5-turbo',
    'messages' => [...],
    'stream' => true,
]);

foreach ($response as $chunk) {
    echo $chunk->choices[0]->delta->content;
}

2. Structured Outputs (JSON Mode)

$response = OpenAI::chat()->create([
    'model' => 'gpt-3.5-turbo-0613',
    'messages' => [...],
    'response_format' => ['type' => 'json_object'],
]);

$data = json_decode($response->choices[0]->message->content, true);

3. Async Requests (For Background Processing)

use OpenAI\Resources\Chat;

$response = OpenAI::chat()->create([
    'model' => 'gpt-4',
    'messages' => [...],
    'stream' => false,
]);

// Store $response->id for later retrieval
$job = new ProcessOpenAIResponse($response->id);
dispatch($job);

4. Error Handling

try {
    $response = OpenAI::chat()->create([...]);
} catch (\OpenAI\Exceptions\RateLimitException $e) {
    // Retry with exponential backoff
    sleep(2 ** $e->getRetryAfter());
    retry();
} catch (\OpenAI\Exceptions\InvalidRequestException $e) {
    // Validate input data
    Log::error('OpenAI validation error:', ['error' => $e->getMessage()]);
}

Integration Tips

1. Service Layer Abstraction

Create a dedicated service class to encapsulate OpenAI logic:

class AIService {
    public function generateSummary(string $content): string {
        $response = OpenAI::chat()->create([
            'model' => 'gpt-3.5-turbo',
            'messages' => [
                ['role' => 'system', 'content' => 'Summarize the following text.'],
                ['role' => 'user', 'content' => $content],
            ],
            'max_tokens' => 100,
        ]);

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

2. Caching Responses

use Illuminate\Support\Facades\Cache;

public function getCachedResponse(string $prompt): string {
    return Cache::remember("ai_{$prompt}", now()->addHours(1), function() use ($prompt) {
        return OpenAI::chat()->create([...])->choices[0]->message->content;
    });
}

3. Dynamic Model Selection

public function selectModel(string $taskType): string {
    return match ($taskType) {
        'summary' => 'gpt-3.5-turbo',
        'code' => 'code-davinci-002',
        'default' => 'gpt-4',
    };
}

4. Testing Strategy

// Unit test example
public function test_ai_summary_generation() {
    OpenAI::fake([
        Chat\CreateResponse::fake([
            'choices' => [
                ['message' => ['content' => 'Test summary']],
            ],
        ]),
    ]);

    $summary = $this->aiService->generateSummary('Test content');
    $this->assertEquals('Test summary', $summary);

    OpenAI::assertSent(Chat\Create::class, function ($method, $parameters) {
        return $method === 'create' &&
               $parameters['messages'][1]['content'] === 'Test content';
    });
}

Gotchas and Tips

Pitfalls

1. Rate Limits

   • OpenAI enforces strict rate limits (e.g., 3,000 tokens/min for gpt-3.5-turbo).
   • Fix: Use OpenAI::setRateLimitHandler() to implement custom retry logic or cache responses aggressively.
   • Debugging: Check X-RateLimit-* headers in the response.

2. Token Count Mismanagement

   • Underestimating token usage leads to truncated responses or errors.
   • Tip: Use OpenAI::tokenizer()->countTokens($text) to validate input length before calling the API.

3. Streaming Quirks

   • Streaming responses require proper chunk handling. Missing yield or improper loop termination can cause memory leaks.
   • Example Fix:

     $response = OpenAI::chat()->create([..., 'stream' => true]);
     foreach ($response as $chunk) {
         if (isset($chunk->choices[0]->delta->content)) {
             echo $chunk->choices[0]->delta->content;
         }
         // Critical: Flush output buffer to avoid buffering issues
         if (function_exists('ob_flush')) ob_flush();
         flush();
     }
     

4. Facade vs. Direct Client

   • The facade (OpenAI::chat()) is convenient but less flexible than the underlying client (\OpenAI\Client).
   • When to use direct client:

     $client = app(\OpenAI\Client::class);
     $response = $client->chat()->create([...]); // For advanced use cases
     

5. Environment-Specific Config

   • Hardcoding API keys in config/openai.php bypasses Laravel’s environment system.
   • Best Practice: Always rely on .env variables. The package respects OPENAI_API_KEY by default.

Debugging Tips

1. Enable HTTP Logging Add to config/logging.php:

   'channels' => [
       'openai' => [
           'driver' => 'monolog',
           'handler' => \OpenAI\Laravel\Logging\OpenAIHandler::class,
           'with' => ['tag' => 'openai'],
       ],
   ],
   

   Then use:

   OpenAI::setLogger(app('log')->channel('openai'));
   

2. Validate API Responses Use dd() or dump() on the full response object to inspect:

   $response = OpenAI::chat()->create([...]);
   dd($response->toArray()); // Inspect raw data
   

3. Common HTTP Errors

   • 429 (Rate Limit): Implement exponential backoff.
   • 401 (Unauthorized): Verify OPENAI_API_KEY and organization.
   • 400 (Bad Request): Validate input parameters (e.g., messages array structure).

Extension Points

1. Custom Headers Override default headers in the service provider:

   // app/Providers/OpenAIServiceProvider.php
   public function register() {
       $this->app->singleton(\OpenAI\Client::class, function ($app) {
           $client = OpenAI::client([
               'headers' => [
                   'Custom-Header' => 'value',
               ],
           ]);
           return $client;
       });
   }
   

2. Middleware for Requests Add preprocessing/POST-processing:

   OpenAI::setRequestMiddleware(function ($request) {
       $request->withHeader('X-Custom-ID', Str::uuid());
   });
   
   OpenAI::setResponseMiddleware(function ($response) {
       if ($response->statusCode === 200) {
           $response->withHeader('X-Processed', 'true');
       }
   });
   

3. Event Listeners