Laravel Gemini Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require hosseinhezami/laravel-gemini
   php artisan vendor:publish --provider="Hosseinhezami\Gemini\GeminiServiceProvider" --tag="config"
   

   • Publishes the config file at config/gemini.php.

2. Environment Configuration Add your Google API key to .env:

   GEMINI_API_KEY=your_api_key_here
   

3. First Use Case: Basic Text Generation

   use Hosseinhezami\Gemini\Gemini;
   
   $response = Gemini::prompt("What is Laravel?");
   echo $response->text();
   

Key Configuration

• Review config/gemini.php for:
  • Default model (gemini.model).
  • API endpoint (gemini.endpoint).
  • Caching settings (gemini.cache).
  • Timeout and retry logic.

Implementation Patterns

Workflows

1. Structured Output (JSON)

   $response = Gemini::prompt("Summarize this in JSON: {text}", [
       'structuredOutput' => [
           'schema' => [
               'type' => 'object',
               'properties' => [
                   'summary' => ['type' => 'string'],
                   'keyPoints' => ['type' => 'array', 'items' => ['type' => 'string']],
               ],
           ],
       ],
   ]);
   $data = $response->json();
   

2. Function Calling

   $response = Gemini::prompt("Book a flight from NYC to LA", [
       'functions' => [
           [
               'name' => 'book_flight',
               'description' => 'Book a flight',
               'parameters' => [
                   'type' => 'object',
                   'properties' => [
                       'departure' => ['type' => 'string'],
                       'destination' => ['type' => 'string'],
                   ],
               ],
           ],
       ],
   ]);
   $actions = $response->actions();
   

3. File Uploads (Multimodal)

   $filePath = storage_path('image.jpg');
   $response = Gemini::prompt("Describe this image", [
       'files' => [$filePath],
   ]);
   

Integration Tips

• Caching Responses Enable caching in config/gemini.php:

  'cache' => [
      'enabled' => true,
      'driver' => 'redis',
      'prefix' => 'gemini_',
  ],
  

  Cache responses for 5 minutes by default; override via:

  $response = Gemini::prompt("...", ['cache' => ['ttl' => 3600]]);
  

• Rate Limiting Use middleware to throttle requests:

  use Hosseinhezami\Gemini\Middleware\ThrottleGeminiRequests;
  
  $router->middleware(ThrottleGeminiRequests::class);
  

• Queueing Long Requests Dispatch jobs for async processing:

  use Hosseinhezami\Gemini\Jobs\ProcessGeminiRequest;
  
  ProcessGeminiRequest::dispatch("Your long prompt here");
  

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never commit .env or hardcode keys. Use Laravel's .env or a secrets manager.
   • Validate the key in config/gemini.php:

     'validate_key' => env('APP_ENV') !== 'local',
     

2. Rate Limits

   • Default limit: 60 requests/minute (Gemini Pro). Monitor usage via:

     $rateLimit = Gemini::rateLimit();
     

   • Implement exponential backoff for retries:

     'retry' => [
         'max_attempts' => 3,
         'delay' => 1000, // ms
     ],
     

3. Structured Output Parsing

   • Invalid schemas may return raw text. Validate responses:

     if ($response->isStructured()) {
         $data = $response->json();
     } else {
         $data = ['error' => 'Invalid structured output'];
     }
     

4. File Size Limits

   • Max file size: 2MB per request. Compress images/videos before upload.

Debugging

• Enable Logging

  'debug' => [
      'enabled' => true,
      'log_requests' => true,
      'log_responses' => true,
  ],
  

  Logs appear in storage/logs/gemini.log.

• Common Errors

  Error	Solution
  Invalid API Key	Verify GEMINI_API_KEY in .env.
  Rate Limit Exceeded	Check Gemini::rateLimit() and implement retries.
  Invalid JSON Schema	Validate schema syntax (use JSON Schema Validator).
  File Too Large	Compress files or split into chunks.
  Model Not Found	Ensure gemini.model in config matches a valid Gemini model (e.g., gemini-pro).

Extension Points

1. Custom Models Override the default model dynamically:

   $response = Gemini::setModel('gemini-1.5-flash')->prompt("Your prompt");
   

2. Event Listeners Listen for request/response events:

   use Hosseinhezami\Gemini\Events\RequestSent;
   use Hosseinhezami\Gemini\Events\ResponseReceived;
   
   Event::listen(RequestSent::class, function ($event) {
       logger()->info('Gemini request sent', $event->payload);
   });
   

3. Service Provider Extensions Bind custom Gemini clients:

   $this->app->bind(Gemini::class, function ($app) {
       return new CustomGeminiClient($app['config']['gemini']);
   });
   

4. Testing Use the GeminiFake class for unit tests:

   use Hosseinhezami\Gemini\Testing\GeminiFake;
   
   public function test_gemini_response()
   {
       GeminiFake::fake([
           'What is Laravel?' => 'A PHP framework...',
       ]);
   
       $response = Gemini::prompt("What is Laravel?");
       $this->assertEquals('A PHP framework...', $response->text());
   }