Php Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require apisearch-io/php-client
   

   Ensure your Laravel project meets PHP 8.0+ requirements.

2. First Use Case: Searching Documents Initialize the client in config/services.php:

   'apisearch' => [
       'api_key' => env('APISEARCH_API_KEY'),
       'endpoint' => env('APISEARCH_ENDPOINT', 'https://api.apisearch.io'),
   ],
   

   Then register the service provider in config/app.php:

   'providers' => [
       // ...
       Apisearch\Client\ApisearchServiceProvider::class,
   ],
   

3. Basic Search Query Inject the client via Laravel’s DI:

   use Apisearch\Client\ApisearchClient;
   
   public function search(ApisearchClient $client)
   {
       $results = $client->search('documents', [
           'query' => 'laravel framework',
           'limit' => 10,
       ]);
       return response()->json($results);
   }
   

Implementation Patterns

Common Workflows

1. Index Management

   • Create/Update Index:

     $client->index('products')->createOrUpdate([
         'id' => '123',
         'title' => 'Laravel Package',
         'description' => 'A PHP package for Laravel...',
     ]);
     

   • Bulk Operations:

     $client->index('products')->bulk([
         ['id' => '1', 'name' => 'Item 1'],
         ['id' => '2', 'name' => 'Item 2'],
     ]);
     

2. Advanced Queries

   • Filtering:

     $results = $client->search('products', [
         'query' => 'package',
         'filter' => [
             'price' => ['gt' => 10],
             'category' => 'laravel',
         ],
     ]);
     

   • Aggregations:

     $results = $client->search('products', [
         'aggregations' => [
             'categories' => ['field' => 'category'],
         ],
     ]);
     

3. Integration with Laravel Ecosystem

   • Queue Jobs for Async Indexing:

     use Apisearch\Client\Jobs\IndexDocument;
     
     IndexDocument::dispatch($client, 'products', $documentData);
     

   • Cache Responses:

     $cacheKey = 'apisearch_products_laravel';
     $results = Cache::remember($cacheKey, now()->addHours(1), function () use ($client) {
         return $client->search('products', ['query' => 'laravel']);
     });
     

4. Webhook Handling

   • Listen for index updates via Laravel’s HandleIncomingWebhook:

     public function handle(Request $request)
     {
         $payload = $request->json()->all();
         // Process webhook (e.g., sync local DB)
     }
     

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The client does not auto-retry on rate limits. Implement middleware:

     $client->setMiddleware(function ($request, $next) {
         if ($request->hasHeader('x-rate-limit-remaining') && $request->header('x-rate-limit-remaining') == '0') {
             sleep(1);
         }
         return $next($request);
     });
     

2. Pagination Quirks

   • Use offset and limit for cursor-based pagination:

     $results = $client->search('products', [
         'query' => 'laravel',
         'limit' => 20,
         'offset' => 0, // Start from 0
     ]);
     

3. Schema Validation

   • The API enforces schema validation. Test with validate: true in bulk operations:

     $client->index('products')->bulk($data, ['validate' => true]);
     

Debugging

• Enable Debug Mode:

  $client->setDebug(true); // Logs requests/responses to storage/logs/apisearch.log
  

• Validate API Key:

  php artisan tinker
  >>> $client = app(Apisearch\Client\ApisearchClient::class);
  >>> $client->ping(); // Returns API status
  

Extension Points

1. Custom HTTP Client Override the default Guzzle client:

   $client->setHttpClient(new CustomGuzzleClient());
   

2. Event Listeners Subscribe to index events (e.g., IndexCreated):

   event(new IndexCreated('products', $indexData));
   

3. Local Testing Use the APISEARCH_ENDPOINT env var to point to a local instance:

   APISEARCH_ENDPOINT=http://localhost:9200