Seal Symfony Bundle Laravel Package

Getting Started

Minimal Steps

1. Install the Bundle & Adapter

   composer require cmsig/seal-symfony-bundle cmsig/seal-elasticsearch-adapter
   

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

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Cmsig\SealBundle\SealBundle::class => ['all' => true],
   ];
   

3. Configure the Adapter Define your adapter in config/packages/seal.yaml:

   seal:
       adapter: elasticsearch
       elasticsearch:
           host: 'localhost'
           port: 9200
   

4. First Use Case: Basic Search Inject the SealClient service and execute a query:

   use Cmsig\SealBundle\Client\SealClientInterface;
   
   class MyController
   {
       public function __construct(private SealClientInterface $sealClient) {}
   
       public function search(Request $request)
       {
           $query = $this->sealClient->query()
               ->addText('title', $request->query->get('q'))
               ->execute();
   
           return $this->json($query->getResults());
       }
   }
   

Where to Look First

• SEAL Documentation (Core concepts, query building).
• config/packages/seal.yaml (Adapter-specific configurations).
• src/Client/SealClientInterface (API contract for queries).

Implementation Patterns

Core Workflows

1. Query Building Chain methods for complex queries:

   $query = $this->sealClient->query()
       ->addText('content', 'laravel')
       ->addFilter('category', 'tutorial')
       ->setPage(2, 10)
       ->sort('published_at', 'desc');
   

2. Index Management Define indexes via YAML (e.g., config/packages/seal_indexes.yaml):

   seal:
       indexes:
           articles:
               adapter: elasticsearch
               settings:
                   analyzer: 'english'
               mappings:
                   title: { type: 'text' }
                   content: { type: 'text' }
   

   Register indexes programmatically:

   $this->sealClient->index('articles')->create();
   

3. Event-Driven Indexing Use Symfony events to sync data (e.g., after entity persistence):

   // In a listener
   $this->sealClient->index('articles')->addDocument($article->toArray());
   

4. Dependency Injection Bind custom adapters or services:

   # config/services.yaml
   services:
       App\Service\CustomSealAdapter:
           arguments:
               - '@seal.client'
   

Integration Tips

• Doctrine ORM Sync: Use cmsig/seal-doctrine-adapter to auto-index entities.
• API Layer: Expose search via API Platform or Symfony’s JsonResponse.
• Testing: Mock SealClientInterface with cmsig/seal-memory-adapter for unit tests.

Gotchas and Tips

Pitfalls

1. Adapter-Specific Quirks

   • Elasticsearch: Validate settings and mappings against Elasticsearch schema.
   • MemoryAdapter: Not persistent; reset on app restart.

2. Query Performance

   • Avoid unbounded addText() fields without analyzer or search_analyzer.
   • Use addFilter() for exact matches (e.g., categories) to reduce query load.

3. Configuration Overrides

   • Bundle configs in seal.yaml override defaults. Use !import to merge:

     seal:
         !import '@seal/config.yaml'
         indexes:
             articles: { settings: { ... } }
     

4. Debugging

   • Enable SEAL logging in config/packages/monolog.yaml:

     handlers:
         seal:
             type: stream
             path: '%kernel.logs_dir%/seal.log'
             level: debug
     

   • Dump raw queries with:

     $query->getRawQuery(); // Returns adapter-specific query object
     

Extension Points

1. Custom Adapters Implement Cmsig\Seal\Adapter\AdapterInterface and register via:

   seal:
       adapters:
           custom:
               class: App\Adapter\CustomSealAdapter
               arguments: ['@service_id']
   

2. Query Transformers Extend Cmsig\Seal\Query\QueryBuilder to add domain-specific methods:

   class AppQueryBuilder extends QueryBuilder
   {
       public function addFuzzyText(string $field, string $value): self
       {
           return $this->addText($field, $value)->setFuzziness(2);
       }
   }
   

   Bind in services.yaml:

   services:
       App\Query\AppQueryBuilder: ~
   

3. Event Listeners Subscribe to seal.index.created or seal.query.executed events:

   // src/EventListener/SealListener.php
   public static function getSubscribedEvents(): array
   {
       return [
           'seal.query.executed' => 'onQueryExecuted',
       ];
   }
   

Pro Tips

• Bulk Indexing: Use index()->addDocuments([...]) for batch inserts.
• Pagination: Leverage setPage() and getTotalResults() for UI controls.
• Security: Sanitize user input in queries to prevent query injection.