Seal Algolia Adapter Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require cmsig/seal cmsig/seal-algolia-adapter
   

2. Configure Algolia Client Use either direct instantiation or DSN-based configuration:

   // Direct client
   $client = SearchClient::create('APP_ID', 'ADMIN_API_KEY');
   
   // Or via DSN (e.g., in .env)
   $client = SearchClient::createFromEnv('algolia://APP_ID:ADMIN_API_KEY');
   

3. Initialize SEAL Engine

   use CmsIg\Seal\Engine;
   use CmsIg\Seal\Adapter\Algolia\AlgoliaAdapter;
   
   $engine = new Engine(
       new AlgoliaAdapter($client),
       $schema // Your SEAL schema definition
   );
   

4. First Use Case: Indexing Data

   $engine->index('products', [
       ['id' => 1, 'name' => 'Laptop', 'price' => 999.99],
       ['id' => 2, 'name' 'Phone', 'price' => 699.99],
   ]);
   

Implementation Patterns

Core Workflows

1. Schema-Driven Indexing Leverage SEAL’s schema to enforce data structure consistency before indexing:

   $schema = new \CmsIg\Seal\Schema\Builder()
       ->addField('id', 'integer', true)
       ->addField('name', 'string', true)
       ->addField('price', 'float', false);
   

2. Bulk Operations Use Algolia’s bulk API for efficiency:

   $engine->bulkIndex('products', $dataArray);
   

3. Search Integration Combine with SEAL’s search abstraction:

   $results = $engine->search('products', 'laptop', [
       'hitsPerPage' => 10,
       'attributesToRetrieve' => ['name', 'price'],
   ]);
   

Laravel-Specific Patterns

1. Service Provider Binding Bind the engine in AppServiceProvider:

   $this->app->singleton('algolia.engine', function ($app) {
       $client = SearchClient::createFromEnv('algolia://APP_ID:ADMIN_API_KEY');
       return new Engine(new AlgoliaAdapter($client), $app['seal.schema']);
   });
   

2. Query Builder Integration Extend Laravel’s query builder for Algolia-specific searches:

   class AlgoliaQueryBuilder extends Builder {
       public function algoliaSearch($query) {
           return $this->engine->search($this->model, $query);
       }
   }
   

3. Event-Driven Indexing Sync models with Algolia via Laravel events (e.g., saved, deleted):

   Product::saved(function ($product) {
       app('algolia.engine')->index('products', $product->toArray());
   });
   

Gotchas and Tips

Common Pitfalls

1. Schema Mismatches

   • Algolia enforces strict schema compliance. Validate SEAL schemas against Algolia’s index settings.
   • Fix: Use AlgoliaAdapter::validateSchema() to catch mismatches early.

2. Rate Limits

   • Algolia’s free tier has strict rate limits. Monitor usage via:

     $client->getApiClient()->getUsage();
     

   • Tip: Implement exponential backoff for retries:

     use Symfony\Component\Process\Exception\TimeoutException;
     
     try {
         $engine->index(...);
     } catch (TimeoutException $e) {
         sleep(2 ** $attempt); // Exponential backoff
         retry();
     }
     

3. DSN Security

   • Hardcoding API keys in .env is risky. Use Laravel’s vault or environment variables with restricted permissions:

     ALGOLIA_APP_ID=your_app_id
     ALGOLIA_API_KEY=${VAULT:algolia_key}  # Using Laravel Vault
     

Debugging Tips

1. Enable Algolia Debug Mode

   $client->setDebug(); // Logs all API requests/responses
   

2. Inspect Raw Algolia Responses Access the underlying client for debugging:

   $response = $engine->getAdapter()->getClient()->search('products', 'query');
   dd($response->getResults());
   

3. Handle Partial Failures Algolia’s bulk API may partially fail. Check for errors:

   $result = $engine->bulkIndex('products', $data);
   if ($result->hasErrors()) {
       foreach ($result->getErrors() as $error) {
           log::error("Algolia bulk index error: " . $error->getMessage());
       }
   }
   

Extension Points

1. Custom Index Settings Override default Algolia settings via the adapter:

   $adapter = new AlgoliaAdapter($client, [
       'settings' => [
           'searchableAttributes' => ['name', 'description'],
           'customRanking' => ['desc(price)'],
       ],
   ]);
   

2. Pre/Post-Index Hooks Extend the adapter to modify payloads:

   class CustomAlgoliaAdapter extends AlgoliaAdapter {
       public function index($index, $objects) {
           $objects = $this->transformObjects($objects);
           parent::index($index, $objects);
       }
   
       protected function transformObjects($objects) {
           // Add custom fields (e.g., timestamps)
           return array_map(function ($obj) {
               $obj['_updatedAt'] = now()->toIso8601String();
               return $obj;
           }, $objects);
       }
   }
   

3. Fallback Strategies Implement a fallback to local search if Algolia fails:

   $engine = new Engine(
       new AlgoliaAdapter($client),
       $schema,
       new LocalSearchFallback() // Custom fallback adapter
   );