Laravel Serpapi Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tipoff/laravel-serpapi
   

   Publish the config file:

   php artisan vendor:publish --provider="Tipoff\SerpApi\SerpApiServiceProvider"
   

2. Configuration Edit .env and add:

   SERPAPI_KEY=your_api_key_here
   

   Verify the config in config/serpapi.php.

3. First Use Case Fetch a Google search result in a controller:

   use Tipoff\SerpApi\SerpApi;
   
   public function search()
   {
       $results = SerpApi::search('laravel serpapi', 'google');
       return response()->json($results);
   }
   

Implementation Patterns

Core Workflows

1. Search Queries Use the facade for common search types:

   // Google search
   $google = SerpApi::search('laravel', 'google');
   
   // YouTube search
   $youtube = SerpApi::search('laravel tutorial', 'youtube');
   
   // Custom engine
   $custom = SerpApi::search('query', 'custom_engine', ['param' => 'value']);
   

2. Result Processing Extract structured data from responses:

   $results = SerpApi::search('laravel jobs', 'google');
   $organicResults = collect($results['organic_results'] ?? []);
   

3. Rate Limiting & Retries Handle API limits gracefully:

   try {
       $data = SerpApi::search('query', 'google', [], 3); // Retry 3 times
   } catch (\Tipoff\SerpApi\Exceptions\RateLimitException $e) {
       // Log or queue for later
   }
   

Integration Tips

• Queue Delayed Requests Use Laravel Queues to avoid hitting rate limits:

  SearchJob::dispatch('query')->delay(now()->addMinutes(1));
  

• Cache Responses Cache frequent queries (e.g., product searches):

  $results = Cache::remember("serpapi_{$query}", now()->addHours(1), function() use ($query) {
      return SerpApi::search($query, 'google');
  });
  

• API Key Rotation Store keys in the database and rotate via a scheduler:

  config(['serpapi.key' => DB::table('api_keys')->where('active', 1)->value('key')]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Methods The package is outdated (last release 2021). Check SerpAPI’s official docs for breaking changes in their API.

   • Workaround: Extend the facade or use raw HTTP calls if needed:

     $client = new \GuzzleHttp\Client();
     $response = $client->get('https://serpapi.com/search', [
         'query' => [
             'q' => 'laravel',
             'api_key' => config('serpapi.key'),
         ]
     ]);
     

2. Missing Error Handling The package lacks granular exception handling for different HTTP statuses.

   • Tip: Wrap calls in a custom handler:

     try {
         $results = SerpApi::search('query', 'google');
     } catch (\Tipoff\SerpApi\Exceptions\SerpApiException $e) {
         if ($e->getCode() === 429) {
             // Rate limited
         }
         if ($e->getCode() === 401) {
             // Invalid API key
         }
     }
     

3. Config Overrides The config/serpapi.php may not support all SerpAPI parameters. Extend the config:

   'engines' => [
       'google' => [
           'params' => [
               'hl' => 'en', // Default language
               'gl' => 'us', // Default country
           ],
       ],
   ],
   

Debugging Tips

• Log Raw Responses Add a middleware to log responses for debugging:

  public function handle($request, Closure $next)
  {
      $response = $next($request);
      if ($request->routeIs('serpapi.*')) {
          \Log::debug('SerpAPI Response:', [
              'data' => $response->getData(),
              'status' => $response->getStatusCode(),
          ]);
      }
      return $response;
  }
  

• Validate API Key Test the key manually first:

  curl "https://serpapi.com/search.json?q=test&api_key=YOUR_KEY"
  

Extension Points

1. Custom Engines Add support for unsupported engines by extending the SerpApi facade:

   // app/Providers/SerpApiServiceProvider.php
   public function boot()
   {
       SerpApi::extend('bing', function ($query, $params = []) {
           return $this->call('bing', $query, $params);
       });
   }
   

2. Response Transformers Create a transformer to normalize responses:

   class GoogleSearchTransformer
   {
       public static function transform($data)
       {
           return collect($data['organic_results'] ?? [])
               ->map(fn($result) => [
                   'title' => $result['title'],
                   'url' => $result['link'],
                   'snippet' => $result['snippet'],
               ]);
       }
   }
   

3. Mocking for Tests Use a mock HTTP client in tests:

   $this->mock(SerpApi::class)->shouldReceive('search')
       ->once()
       ->andReturn(['organic_results' => []]);