Seal Elasticsearch Adapter Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require cmsig/seal cmsig/seal-elasticsearch-adapter elastic/elasticsearch
   

   Ensure elastic/elasticsearch is installed for the Elasticsearch client.

2. Basic Initialization:

   use CmsIg\Seal\Engine;
   use CmsIg\Seal\Adapter\Elasticsearch\ElasticsearchAdapter;
   use Elastic\Elasticsearch\ClientBuilder;
   
   $client = ClientBuilder::create()->setHosts(['127.0.0.1:9200'])->build();
   $adapter = new ElasticsearchAdapter($client);
   $engine = new Engine($adapter, $schema); // $schema is your SEAL schema definition
   

3. First Use Case: Index a document:

   $engine->index('documents', ['id' => 1, 'title' => 'Test', 'content' => 'Hello']);
   

Where to Look First

• Adapter Class: ElasticsearchAdapter in src/Adapter/Elasticsearch/
• SEAL Engine: Review Engine class for core search operations (index, search, delete).
• DSN Support: Use elasticsearch:// in .env for framework integration (e.g., Laravel’s config/elasticsearch.php).

Implementation Patterns

Core Workflows

1. Indexing Documents:

   $engine->index('index_name', $document);
   

   • Maps SEAL’s index() to Elasticsearch’s index() API.
   • Automatically handles document IDs and schema validation.

2. Searching:

   $results = $engine->search('index_name', ['query' => ['match' => ['title' => 'Test']]]);
   

   • Translates SEAL queries to Elasticsearch’s query DSL.
   • Returns SearchResult objects with hits, aggregations, etc.

3. Bulk Operations:

   $engine->bulkIndex('index_name', [$doc1, $doc2]);
   

   • Uses Elasticsearch’s bulk API for efficiency.

Integration Tips

• Schema Management: Define your SEAL schema with mappings (e.g., text, keyword types) to align with Elasticsearch’s capabilities.

  $schema = new Schema();
  $schema->addField('title', Field::text()->analyzed());
  

• Error Handling: Wrap operations in try-catch blocks to handle Elasticsearch exceptions (e.g., Elasticsearch\Common\Exceptions\ElasticsearchException).

  try {
      $engine->index('index_name', $doc);
  } catch (\Exception $e) {
      \Log::error("Elasticsearch error: " . $e->getMessage());
  }
  

• Configuration: Use Laravel’s config/elasticsearch.php for reusable client settings:

  'connections' => [
      'default' => [
          'hosts' => ['127.0.0.1:9200'],
          'tls' => env('ELASTICSEARCH_TLS', false),
      ],
  ],
  

• Framework-Specific Helpers: Create a facade or service provider to simplify instantiation:

  // app/Providers/ElasticsearchServiceProvider.php
  public function register() {
      $this->app->singleton(Engine::class, function ($app) {
          $client = ClientBuilder::create()->setHosts(config('elasticsearch.hosts'))->build();
          return new Engine(new ElasticsearchAdapter($client), $app->make(Schema::class));
      });
  }
  

Gotchas and Tips

Pitfalls

1. Schema Mismatches:

   • SEAL’s schema must match Elasticsearch’s mapping. For example, SEAL’s Field::text() maps to Elasticsearch’s text type, but ensure analyzers (e.g., standard, custom) are configured.
   • Fix: Validate schema before indexing or use Elasticsearch’s dynamic mapping cautiously.

2. Connection Issues:

   • Elasticsearch client may fail silently if the server is unreachable. Always test connections:

   $client->ping();
   

3. Bulk API Limits:

   • Elasticsearch’s bulk API has a default payload size limit (~100MB). Large batches may fail.
   • Fix: Use ClientBuilder::create()->setRetryOnConflict(3) or split bulk operations.

4. Deprecation Warnings:

   • The package is under active development. Check the main SEAL repo for breaking changes.

Debugging

• Enable Logging: Configure the Elasticsearch client to log requests/responses:

  $client = ClientBuilder::create()
      ->setHosts(['127.0.0.1:9200'])
      ->setLogger(new \Monolog\Logger('elasticsearch'))
      ->build();
  

• Query DSL Errors: Elasticsearch may return malformed query errors. Validate queries using:

  $client->validateQuery(['query' => ['match' => ['title' => 'Test']]]);
  

Extension Points

1. Custom Mappings: Override default field mappings by extending ElasticsearchAdapter:

   class CustomElasticsearchAdapter extends ElasticsearchAdapter {
       protected function getFieldType(Field $field) {
           if ($field->getName() === 'custom_field') {
               return 'custom_type';
           }
           return parent::getFieldType($field);
       }
   }
   

2. Query Modifiers: Extend search behavior by hooking into the query builder:

   $engine->search('index_name', ['query' => ['match' => ['title' => 'Test']]], function ($query) {
       $query['track_total_hits'] = true; // Add Elasticsearch-specific options
   });
   

3. Index Management: Use the adapter to manage indices (e.g., aliases, settings):

   $adapter->getClient()->indices()->create(['index' => 'new_index', 'body' => ['settings' => ['number_of_shards' => 3]]]);
   

Configuration Quirks

• DSN Parsing: The DSN format (elasticsearch://user:pass@host:port?tls=true) is supported but may not handle all edge cases (e.g., spaces in passwords). Use explicit client configuration for complex setups.

• TLS/SSL: Ensure openssl is enabled in PHP and configure CA certificates:

  $client = ClientBuilder::create()
      ->setHosts(['127.0.0.1:9200'])
      ->setSSLVerification(true)
      ->setCACert('/path/to/ca.crt')
      ->build();