Seal Typesense Adapter Laravel Package

Getting Started

Minimal Steps to Begin

1. Install Dependencies

   composer require cmsig/seal cmsig/seal-typesense-adapter
   

2. Configure Typesense Client Create a Typesense client instance with your API key, nodes, and HTTP client:

   use Typesense\Client;
   use Http\Client\Curl\Client as CurlClient;
   use Http\Discovery\Psr17FactoryDiscovery;
   
   $client = new Client([
       'api_key' => env('TYPESENSE_API_KEY'),
       'nodes' => [
           ['host' => env('TYPESENSE_HOST'), 'port' => env('TYPESENSE_PORT'), 'protocol' => env('TYPESENSE_PROTOCOL', 'http')],
       ],
       'client' => new CurlClient(
           Psr17FactoryDiscovery::findResponseFactory(),
           Psr17FactoryDiscovery::findStreamFactory()
       ),
   ]);
   

3. Initialize SEAL Engine Pass the Typesense adapter and your schema to the SEAL engine:

   use CmsIg\Seal\Adapter\Typesense\TypesenseAdapter;
   use CmsIg\Seal\Engine;
   
   $adapter = new TypesenseAdapter($client);
   $engine = new Engine($adapter, $schema);
   

4. First Use Case: Indexing Documents

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

Implementation Patterns

Core Workflows

1. Schema Management Define your schema in SEAL format and let the adapter handle Typesense-specific mappings:

   $schema = new \CmsIg\Seal\Schema\Schema();
   $schema->addField('name', 'text', ['facet' => true]);
   $schema->addField('price', 'float');
   

2. Search Integration Use SEAL’s query builder to interact with Typesense:

   $results = $engine->search('products', 'Laptop', [
       'query_by' => 'name',
       'per_page' => 10,
   ]);
   

3. Bulk Operations Leverage Typesense’s bulk API via SEAL’s batch methods:

   $engine->batch('products', [
       ['id' => 3, 'name' => 'Tablet', 'price' => 399.99],
       ['id' => 4, 'name' => 'Monitor', 'price' => 249.99],
   ], ['action' => 'upsert']);
   

Integration Tips

• Environment Configuration Use .env for Typesense credentials (e.g., TYPESENSE_API_KEY, TYPESENSE_HOST). Example DSN:

  TYPESENSE_DSN=typesense://S3CR3T@127.0.0.1:8108?tls=true
  

• Dependency Injection Register the adapter and engine in Laravel’s service container:

  $this->app->bind(TypesenseAdapter::class, function ($app) {
      return new TypesenseAdapter(new Client([
          'api_key' => $app['config']['typesense.api_key'],
          'nodes' => [['host' => $app['config']['typesense.host']]],
      ]));
  });
  

• Schema Validation Validate SEAL schemas against Typesense’s supported field types (e.g., avoid unsupported types like geopoint if not configured in Typesense).

Gotchas and Tips

Pitfalls

1. Schema Mismatches

   • Typesense requires explicit field definitions (e.g., type, optional). SEAL schemas must align with Typesense’s field types.
   • Fix: Use TypesenseAdapter::validateSchema() or handle exceptions during engine->index().

2. Connection Issues

   • Hardcoded nodes or API keys in code (not .env) can cause deployment failures.
   • Fix: Use Laravel’s config() or environment variables for dynamic configuration.

3. Bulk Operation Limits

   • Typesense’s bulk API has a default limit of 1000 documents per request.
   • Fix: Implement chunking in SEAL’s batch methods or use Typesense’s batch_size parameter.

4. TLS/HTTPS Misconfigurations

   • Forgetting tls=true in the DSN for HTTPS endpoints may fail silently.
   • Fix: Explicitly set protocol: 'https' and tls: true in the client config.

Debugging

• Enable HTTP Logging Use Http\Client\Common\Plugin\LoggerPlugin to log Typesense API requests:

  $client->addPlugin(new LoggerPlugin(new \Psr\Log\NullLogger()));
  

• Check Typesense Server Logs For adapter-specific errors, inspect Typesense’s logs at http://<host>:<port>/debug.

Extension Points

1. Custom Field Mappings Override TypesenseAdapter::mapSchema() to transform SEAL fields into Typesense-specific formats:

   protected function mapSchema(\CmsIg\Seal\Schema\Schema $schema): array {
       $mapped = parent::mapSchema($schema);
       $mapped['fields']['price']['type'] = 'int64'; // Custom mapping
       return $mapped;
   }
   

2. Query Modifiers Extend SEAL’s query builder to support Typesense-specific features (e.g., group_by):

   $engine->search('products', '', [
       'group_by' => 'category',
       'group_limit' => 5,
   ]);
   

3. Retry Logic Implement exponential backoff for transient failures (e.g., network timeouts) using Http\Client\Common\Plugin\RetryPlugin.

Tips

• Use Typesense’s Playground Test queries interactively at http://<host>:<port>/collections/<collection>/documents/playground to debug SEAL-generated queries.

• Leverage SEAL’s Abstraction Switch search backends (e.g., Elasticsearch) without changing application logic by relying on SEAL’s interface.

• Monitor Performance Typesense’s metrics endpoint can help optimize SEAL queries (e.g., avoid * wildcards in query_by).