Seal Laravel Package Laravel Package

Getting Started

Minimal Steps

1. Install the Package & Adapter

   composer require cmsig/seal-laravel-package cmsig/seal-elasticsearch-adapter
   

   (Replace elasticsearch-adapter with your preferred adapter, e.g., memory-adapter for testing.)

2. Publish Configuration

   php artisan vendor:publish --provider="CMSIG\SEAL\Laravel\SEALServiceProvider" --tag="seal-config"
   

   Edit config/seal.php to define your adapter and connection settings.

3. Register the Service Provider Ensure CMSIG\SEAL\Laravel\SEALServiceProvider::class is in config/app.php under providers.

4. First Search Query

   use CMSIG\SEAL\Laravel\Facades\SEAL;
   
   $results = SEAL::search('query', [
       'adapter' => 'elasticsearch', // Matches your config
       'index'   => 'your_index_name',
   ]);
   

Where to Look First

• Config File: config/seal.php (adapter settings, default indices).
• Facade: SEAL::search() for quick queries.
• Adapter Docs: SEAL Core Docs for advanced syntax.

Implementation Patterns

Core Workflows

1. Basic Search

   $results = SEAL::search('laravel', [
       'index' => 'articles',
       'limit' => 10,
   ]);
   

   • Use SEAL::search() for ad-hoc queries.
   • Pass options like index, limit, offset, or filter.

2. Index Management

   // Create/update an index
   SEAL::index('products')->addDocument($productData);
   
   // Delete an index
   SEAL::deleteIndex('products');
   

   • Chain methods for fluent syntax (e.g., SEAL::index('users')->addDocument($user)).

3. Filtering & Facets

   $results = SEAL::search('php', [
       'index'   => 'posts',
       'filter'  => ['tags' => ['php', 'laravel']],
       'facets'  => ['category', 'author'],
   ]);
   

   • Use filter for boolean constraints (e.g., ['price' => ['>' => 100]]).
   • facets returns aggregated metadata (e.g., top tags).

4. Pagination

   $results = SEAL::search('query', [
       'index'  => 'products',
       'limit'  => 20,
       'offset' => 40, // Page 3
   ]);
   

   • Handle pagination manually or wrap results in a LengthAwarePaginator.

5. Adapter-Specific Features

   • Elasticsearch: Use SEAL::rawQuery() for custom DSL:

     $results = SEAL::rawQuery('your_index', [
         'body' => ['query' => ['match' => ['title' => 'laravel']]]
     ]);
     

   • MemoryAdapter: Ideal for testing (data persists in-memory).

Integration Tips

• Laravel Scout Alternative: Replace Scout’s search() with SEAL::search() for cross-engine support.
• Model Bindings: Attach SEAL to Eloquent models via accessors:

  public function getSearchResultsAttribute()
  {
      return SEAL::search($this->title, ['index' => 'products']);
  }
  

• Queue Jobs: Offload heavy indexing to queues:

  SEAL::index('articles')->addDocument($article)->queue();
  

• API Responses: Normalize SEAL results to JSON:

  return response()->json([
      'data' => $results->items(),
      'meta' => ['total' => $results->total()]
  ]);
  

Gotchas and Tips

Pitfalls

1. Adapter Mismatch

   • Issue: Forgetting to install the adapter (e.g., Elasticsearch) or misconfiguring config/seal.php.
   • Fix: Verify adapters array in config matches installed packages. Test with MemoryAdapter first.

2. Index Not Found

   • Issue: Querying a non-existent index throws errors.
   • Fix: Check SEAL::index('name')->exists() before searching. Auto-create indices if needed:

     SEAL::index('dynamic_index')->create();
     

3. Case Sensitivity

   • Issue: Some adapters (e.g., Elasticsearch) default to case-sensitive analysis.
   • Fix: Configure analyzers in your adapter’s settings or use SEAL::rawQuery() for custom mappings.

4. Rate Limiting

   • Issue: Elasticsearch/MemoryAdapter may throttle requests.
   • Fix: Implement retries or use SEAL::search()->retry(3) (if supported).

5. Data Serialization

   • Issue: Complex objects (e.g., Eloquent models) may not serialize correctly.
   • Fix: Use toArray() or custom serializers:

     SEAL::index('users')->addDocument($user->toArray());
     

Debugging

• Log Queries: Enable SEAL logging in config/seal.php:

  'log_queries' => env('SEAL_LOG_QUERIES', false),
  

• Raw Responses: Inspect adapter-specific responses:

  $raw = SEAL::search('query', ['debug' => true]);
  dd($raw->getRawResponse());
  

• Adapter-Specific Tools:
  • Elasticsearch: Use Kibana or curl to verify indices.
  • MemoryAdapter: Check SEAL::index('name')->getDocuments() for live data.

Extension Points

1. Custom Adapters

   • Extend CMSIG\SEAL\Adapter\AbstractAdapter to support new engines (e.g., Algolia, Meilisearch).
   • Register via config/seal.php:

     'adapters' => [
         'custom' => \App\Adapters\CustomAdapter::class,
     ],
     

2. Query Macros

   • Add reusable query builders:

     SEAL::macro('searchProducts', function ($query, $limit = 10) {
         return $this->search($query, [
             'index' => 'products',
             'filter' => ['stock' => ['>' => 0]],
             'limit' => $limit,
         ]);
     });
     

     Usage: SEAL::searchProducts('shoes').

3. Event Listeners

   • Hook into SEAL events (e.g., SEAL.Indexing) for analytics or caching:

     SEAL::listen('SEAL.Indexing', function ($event) {
         Log::info("Indexing {$event->index} started");
     });
     

4. Testing

   • Use MemoryAdapter for unit tests:

     $this->app->singleton('seal', function () {
         return SEAL::make('memory');
     });
     

   • Reset indices between tests:

     SEAL::deleteIndex('test_index');
     

Config Quirks

• Default Adapter: Set in config/seal.php under default_adapter. Override per-query:

  SEAL::search('query', ['adapter' => 'elasticsearch']);
  

• Environment-Specific Settings: Use Laravel’s env() in config:

  'elasticsearch' => [
      'host' => env('ELASTICSEARCH_HOST', 'localhost'),
  ],
  

• Caching: Enable adapter-level caching (if supported) to reduce load:

  'adapters' => [
      'elasticsearch' => [
          'cache' => true,
      ],
  ],