Algoliasearch Client Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

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

   Add to config/services.php (Laravel convention):

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

2. Service Provider (Laravel):

   // app/Providers/AlgoliaServiceProvider.php
   use Algolia\AlgoliaSearch\SearchClient;
   
   class AlgoliaServiceProvider extends ServiceProvider {
       public function register() {
           $this->app->singleton('algolia', function ($app) {
               return SearchClient::create(
                   $app['config']['services.algolia.app_id'],
                   $app['config']['services.algolia.api_key']
               );
           });
       }
   }
   

3. First Use Case (Indexing):

   // app/Services/AlgoliaService.php
   class AlgoliaService {
       protected $client;
   
       public function __construct(SearchClient $client) {
           $this->client = $client;
       }
   
       public function indexProduct(Product $product) {
           $indexName = $this->getIndexName('products');
           $this->client->saveObject($indexName, $product->toAlgoliaArray());
       }
   
       protected function getIndexName(string $type): string {
           return config('services.algolia.index_prefix') . $type;
       }
   }
   

Key First Steps

• Verify credentials via config('services.algolia')
• Test connection with a simple search:

  $response = $this->client->search([
      'indexName' => 'products',
      'query' => 'test',
  ]);
  

Implementation Patterns

Core Workflows

1. Index Management

// Create index
$this->client->initIndex('products', [
    'attributesForFaceting' => ['category', 'brand'],
]);

// Delete index
$this->client->deleteIndex('products');

2. Batch Operations

// Partial update
$this->client->partialUpdateObject('products', '123', [
    'price' => 99.99,
]);

// Batch save
$this->client->saveObjects('products', [
    ['objectID' => '1', 'name' => 'Product 1'],
    ['objectID' => '2', 'name' => 'Product 2'],
]);

3. Search with Advanced Features

$response = $this->client->search([
    'indexName' => 'products',
    'query' => 'laptop',
    'attributesToRetrieve' => ['name', 'price', 'brand'],
    'facets' => ['category', 'brand'],
    'hitsPerPage' => 20,
    'analytics' => true, // Track user behavior
    'clickAnalytics' => true,
]);

4. Async Operations

// Start async task
$task = $this->client->saveObjects('products', $products);

// Wait for completion
$this->client->waitForTask('products', $task['taskID']);

// Poll status
$status = $this->client->getTaskStatus('products', $task['taskID']);

Laravel-Specific Patterns

1. Service Container Integration

// Register with index prefix
$this->app->bind('algolia.index', function ($app, $indexName) {
    $client = $app->make('algolia');
    return $client->initIndex($indexName);
});

// Usage
$productsIndex = app('algolia.index', 'products');

2. Event-Driven Indexing

// Listen to product created event
event(new ProductCreated($product));

// In listener
public function handle(ProductCreated $event) {
    $this->algolia->indexProduct($event->product);
}

3. Query Builder Pattern

class AlgoliaQueryBuilder {
    protected $client;
    protected $index;
    protected $query = [];
    protected $options = [];

    public function __construct(SearchClient $client, string $index) {
        $this->client = $client;
        $this->index = $index;
    }

    public function search(string $query): self {
        $this->query['query'] = $query;
        return $this;
    }

    public function withFacets(array $facets): self {
        $this->options['facets'] = $facets;
        return $this;
    }

    public function execute() {
        return $this->client->search([
            'indexName' => $this->index,
            ...$this->query,
            ...$this->options,
        ]);
    }
}

// Usage
$query = (new AlgoliaQueryBuilder($client, 'products'))
    ->search('laptop')
    ->withFacets(['category', 'brand'])
    ->execute();

4. Model Observers for Sync

// app/Observers/ProductObserver.php
class ProductObserver {
    protected $algolia;

    public function __construct(AlgoliaService $algolia) {
        $this->algolia = $algolia;
    }

    public function saved(Product $product) {
        $this->algolia->indexProduct($product);
    }

    public function deleted(Product $product) {
        $this->algolia->deleteProduct($product->id);
    }
}

Gotchas and Tips

Common Pitfalls

1. Rate Limiting

• Issue: Algolia\AlgoliaSearch\Exceptions\ApiException with 429 status
• Solution: Implement exponential backoff:

  try {
      $response = $this->client->search(...);
  } catch (ApiException $e) {
      if ($e->getStatusCode() === 429) {
          sleep($e->getRetryAfter());
          retry();
      }
      throw $e;
  }
  

2. Empty String Validation

• Issue: Algolia\AlgoliaSearch\Exceptions\InvalidArgumentException for empty strings in required fields
• Fix: Validate inputs:

  $objectID = trim($objectID) ?: uniqid();
  

3. Async Task Timeouts

• Issue: waitForTask() hangs indefinitely
• Fix: Set timeout:

  $this->client->waitForTask('products', $taskID, 30); // 30 seconds
  

4. Index Name Collisions

• Issue: Multiple environments using same index names
• Fix: Use environment-specific prefixes:

  $indexName = config('app.env') . '_' . $baseIndexName;
  

Debugging Tips

1. Enable Debug Logging

$client = SearchClient::create(
    $appId,
    $apiKey,
    ['debug' => true] // Enable debug mode
);

2. Inspect Raw API Calls

// Override HttpClient to log requests
$client->getHttpClient()->setDebug(true);

3. Handle Deprecated Fields

• Example: condition in rules is deprecated (v4.39.1+)
• Fix: Use filter instead:

  $rule = [
      'condition' => ['anchor' => 'category', 'pattern' => 'electronics'],
      // Use filter instead
      'filter' => 'category == "electronics"',
  ];
  

Performance Optimization

1. Batch Processing

// Process in chunks to avoid rate limits
$chunkSize = 1000;
foreach (array_chunk($products, $chunkSize) as $chunk) {
    $this->client->saveObjects('products', $chunk);
    sleep(1); // Respect rate limits
}

2. Parallel Indexing

// Use Laravel's parallel processing
Parallel::for($products, 5, function ($product) {
    $this->algolia->indexProduct($product);
});

3. Cache Responses

// Cache search results (5 minutes)
$cacheKey = "algolia:products:{$query}";
$response = Cache::remember($cacheKey, now()->addMinutes(5), function () use ($query) {
    return $this->client->search(['indexName' => 'products', 'query' => $query]);
});

Advanced Features

1. Custom HTTP Client

// Use Guzzle with custom config
$client = SearchClient::create(
    $appId,
    $apiKey,
    [
        'httpClient' => new GuzzleHttp\Client([
            'timeout' => 30,
            'connect_timeout' => 10,
            'headers' => [
                'User-Agent' => 'MyApp/1.0',
            ],
        ]),
    ]
);

2. Retry Strategy

//