Seal Meilisearch Adapter Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require cmsig/seal cmsig/seal-meilisearch-adapter
   

2. Configure Meilisearch Client:

   use Meilisearch\Client;
   use CmsIg\Seal\Adapter\Meilisearch\MeilisearchAdapter;
   use CmsIg\Seal\Engine;
   
   $client = new Client('http://127.0.0.1:7700'); // Replace with your Meilisearch endpoint
   

3. Initialize SEAL Engine:

   $engine = new Engine(
       new MeilisearchAdapter($client),
       $schema // Your SEAL schema definition
   );
   

First Use Case: Indexing Documents

$document = new \CmsIg\Seal\Document\Document('product', [
    'id' => '123',
    'name' => 'Laptop',
    'price' => 999.99,
]);

$engine->index($document);

Environment-Based Configuration (Laravel)

Add to .env:

MEILISEARCH_DSN=meilisearch://apiKey@127.0.0.1:7700?tls=true

Retrieve in Laravel config:

$dsn = config('services.meilisearch.dsn');
$client = new Client($dsn);

Implementation Patterns

Schema Definition

Define a schema for your documents (e.g., ProductSchema):

use CmsIg\Seal\Schema\Field\Text;
use CmsIg\Seal\Schema\Field\Number;
use CmsIg\Seal\Schema\Schema;

$schema = new Schema('product', [
    'name' => new Text(),
    'price' => new Number(),
]);

Indexing Workflow

1. Batch Indexing:

   $documents = [
       new \CmsIg\Seal\Document\Document('product', ['id' => '1', 'name' => 'Phone']),
       new \CmsIg\Seal\Document\Document('product', ['id' => '2', 'name' => 'Tablet']),
   ];
   $engine->indexMany($documents);
   

2. Upsert (Update or Insert):

   $engine->upsert($document);
   

Querying with SEAL

$results = $engine->search('Laptop', [
    'limit' => 10,
    'attributesToRetrieve' => ['name', 'price'],
]);

Integration with Laravel Services

// services.php
'meilisearch' => function () {
    $client = new Client(config('services.meilisearch.dsn'));
    return new Engine(new MeilisearchAdapter($client), $this->app->make(ProductSchema::class));
},

Event-Driven Indexing (e.g., Model Observers)

// ProductObserver.php
public function saved(Product $product)
{
    $document = new \CmsIg\Seal\Document\Document('product', [
        'id' => $product->id,
        'name' => $product->name,
        'price' => $product->price,
    ]);
    app('meilisearch')->upsert($document);
}

Gotchas and Tips

Debugging

1. Check Meilisearch Logs: Ensure Meilisearch is running and logs are accessible (http://127.0.0.1:7700/docs/health).
2. Adapter-Specific Errors: Wrap operations in try-catch:

   try {
       $engine->index($document);
   } catch (\Meilisearch\Exceptions\MeilisearchException $e) {
       Log::error('Meilisearch error: ' . $e->getMessage());
   }
   

Configuration Quirks

1. DSN Format:

   • Use meilisearch:// for basic connections.
   • Include apiKey@ for authentication.
   • Append ?tls=true for secure connections.
   • Example: meilisearch://admin:masterKey@localhost:7700?tls=true.

2. Schema Mismatches: Validate schema fields against Meilisearch’s supported types (e.g., avoid unsupported types like GeoPoint unless wrapped in a custom field).

Performance Tips

1. Batch Operations: Use indexMany() for bulk inserts/updates to reduce network overhead.
2. Primary Key Handling: Ensure documents have a unique id field (Meilisearch uses this for updates/deletes).

Extension Points

1. Custom Fields: Extend CmsIg\Seal\Schema\Field\Field for Meilisearch-specific types (e.g., RankingField):

   class RankingField extends Field
   {
       public function getMeilisearchType(): string
       {
           return 'ranking';
       }
   }
   

2. Query Modifiers: Leverage Meilisearch’s advanced query syntax via SEAL’s search() method:

   $results = $engine->search('Laptop', [
       'filter' => ['price < 1000'],
       'sort' => ['price:asc'],
   ]);
   

Common Pitfalls

1. Connection Timeouts: Ensure Meilisearch is reachable and the DSN is correct. Test with:

   $client->health(); // Throws exception if unreachable
   

2. Rate Limiting: Meilisearch may throttle requests. Implement exponential backoff in retries:

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

3. Schema Evolution: Meilisearch does not support schema changes post-index creation. Rebuild indices for schema updates:

   meilisearch index create product --primary-key id