Algoliasearch Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require algolia/algoliasearch-client-php "^4.43"
   

   Verify PHP version compatibility (^8.0 required).

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

   'algolia' => [
       'app_id' => env('ALGOLIA_APP_ID'),
       'api_key' => env('ALGOLIA_API_KEY'),
       'index_prefix' => env('ALGOLIA_INDEX_PREFIX', ''),
   ],
   

   Create a helper facade in app/Providers/AppServiceProvider.php:

   use Algolia\AlgoliaSearch\SearchClient;
   use Illuminate\Support\Facades\Facade;
   
   Facade::register('Algolia', function () {
       return SearchClient::create(config('algolia.app_id'), config('algolia.api_key'));
   });
   

3. Basic Indexing:

   $response = Algolia::saveObject('products', [
       'objectID' => '123',
       'name' => 'Laravel T-Shirt',
       'price' => 19.99
   ]);
   

Where to Look First

• Official Documentation for API reference.
• Laravel Scout Extended for Laravel-specific integrations.
• src/Api/ directory for low-level API methods (e.g., SearchApi, IndexingApi).
• New in 4.43.1: Check the Ingestion API fixes for destination payload updates and string parameter validation.

Implementation Patterns

Core Workflows

1. Index Management:

   // Create/update index settings
   Algolia::setSettings('products', ['searchableAttributes' => ['name', 'description']]);
   
   // Delete index
   Algolia::deleteIndex('products');
   

2. Batch Operations:

   // Partial update
   Algolia::partialUpdateObject('products', '123', ['price' => 24.99]);
   
   // Batch indexing
   Algolia::saveObjects('products', [
       ['objectID' => '1', 'name' => 'Item 1'],
       ['objectID' => '2', 'name' => 'Item 2']
   ]);
   

3. Search with Facets:

   $results = Algolia::search([
       'indexName' => 'products',
       'query' => 'laravel',
       'facets' => ['category', 'price_range'],
       'hitsPerPage' => 20
   ]);
   

4. Async Task Handling:

   $taskId = $response['taskID']; // From saveObject/saveObjects
   Algolia::waitForTask('products', $taskId, 5); // Timeout: 5s
   

5. Ingestion API Workflows (Updated in 4.43.1) Leverage the fixed Ingestion API for advanced ingestion workflows:

   // Use the updated destination payload structure
   $ingestionApi = Algolia::getIngestionApi();
   $response = $ingestionApi->pushItems('products', [
       ['objectID' => '1', 'name' => 'Item 1', 'destination' => ['index' => 'products']]
   ]);
   

6. Composition API Workflows (4.43.0) Leverage the improved Composition API for advanced indexing:

   // Define a rule for composition
   $rule = new \Algolia\AlgoliaSearch\Api\CompositionApi\Rule([
       'id' => 'rule_1',
       'conditions' => [['field' => 'category', 'operator' => '==', 'value' => 'electronics']],
   ]);
   
   // Run composition with feedsOrder
   $compositionResponse = Algolia::runComposition('products', [
       'rules' => [$rule],
       'feedsOrder' => ['feed_1', 'feed_2'],
   ]);
   

Laravel Integration Tips

• Scout Integration: Use algolia/scout-extended for Eloquent model indexing:

  use Algolia\ScoutExtended\ScoutExtendedServiceProvider;
  
  ScoutExtendedServiceProvider::configure(function ($config) {
      $config->algolia = [
          'app_id' => config('algolia.app_id'),
          'api_key' => config('algolia.api_key'),
          'index_prefix' => config('algolia.index_prefix'),
      ];
  });
  

• Query Builder: Extend Laravel’s query builder for Algolia searches:

  use Algolia\AlgoliaSearch\SearchClient;
  
  class AlgoliaQueryBuilder extends Builder {
      public function algoliaSearch($query) {
          $results = SearchClient::search([
              'indexName' => $this->getModel()->getAlgoliaIndex(),
              'query' => $query,
          ]);
          return $this->model->hydrate($results['hits']);
      }
  }
  

• Middleware for API Keys: Secure API keys in middleware:

  public function handle($request, Closure $next) {
      config(['algolia.api_key' => $request->user()->algolia_api_key]);
      return $next($request);
  }
  

Advanced Patterns

1. Custom HTTP Client: Override the default HTTP client for logging/retries:

   use Algolia\AlgoliaSearch\Configuration;
   use Algolia\AlgoliaSearch\Transport\CurlHttpClient;
   
   $config = Configuration::create(config('algolia.app_id'), config('algolia.api_key'));
   $config->setHttpClient(new CustomCurlHttpClient());
   $client = new SearchClient($config);
   

2. Retry Strategy: Configure retries for transient failures:

   $config = Configuration::create(config('algolia.app_id'), config('algolia.api_key'));
   $config->setRetryStrategy([
       'max_retries' => 3,
       'delay' => 100, // ms
   ]);
   

3. Logging: Enable debug logging:

   $config = Configuration::create(config('algolia.app_id'), config('algolia.api_key'));
   $config->setDebug(true);
   

4. Ingestion API with Native Connector (Updated in 4.43.1) Use the fixed native connector for ingestion workflows:

   $connector = new \Algolia\AlgoliaSearch\Api\IngestionApi\AlgoliaIndexConnector(
       'products',
       config('algolia.app_id'),
       config('algolia.api_key')
   );
   $connector->pushItems([['objectID' => '1', 'name' => 'Item 1', 'destination' => ['index' => 'products']]]);
   

Gotchas and Tips

Common Pitfalls

1. API Key Permissions:

   • Use search-only keys for frontend searches (no write access).
   • Use admin keys for backend operations (indexing, settings).
   • Gotcha: A 403 Forbidden error often means insufficient API key permissions.

2. Rate Limits:

   • Algolia enforces rate limits. Handle 429 Too Many Requests with retries:

     try {
         $client->search(...);
     } catch (\Algolia\AlgoliaSearch\Exceptions\RateLimitExceededException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

3. Async Task Timeouts:

   • waitForTask() defaults to 30s timeout. Adjust as needed:

     Algolia::waitForTask('products', $taskId, 10); // 10s timeout
     

4. Index Naming:

   • Use index_prefix in config to avoid naming collisions in multi-tenant apps.
   • Gotcha: Index names are case-sensitive.

5. Pagination:

   • Algolia uses page and hitsPerPage for pagination. Avoid offset for large datasets (use cursor-based pagination instead).

6. Empty String Validation (New in 4.43.1):

   • Gotcha: Ensure required string parameters are not empty strings. The library now validates this strictly:

     // This will throw an exception
     Algolia::saveObject('products', [
         'objectID' => '', // Empty string will fail validation
         'name' => 'Item'
     ]);
     

7. Ingestion API Destination Payload (Fixed in 4.43.1):

   • Ensure the destination payload is correctly formatted when using the Ingestion API:

     // Correct format