Typesense Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require acseo/typesense-bundle
   

   Enable in config/bundles.php:

   ACSEO\TypesenseBundle\ACSEOTypesenseBundle::class => ['all' => true],
   

2. Configure .env

   TYPESENSE_URL=http://localhost:8108
   TYPESENSE_KEY=your_api_key_here
   

3. Basic YAML Config

   # config/packages/acseo_typesense.yml
   acseo_typesense:
       typesense:
           url: '%env(resolve:TYPESENSE_URL)%'
           key: '%env(resolve:TYPESENSE_KEY)%'
       collections:
           books:
               entity: App\Entity\Book
               fields:
                   id: id
   

4. First Use Case Inject the TypesenseManager service and search:

   use ACSEO\TypesenseBundle\Service\TypesenseManager;
   
   public function __construct(private TypesenseManager $typesense)
   {
   }
   
   public function searchBooks(string $query): array
   {
       return $this->typesense->search('books', $query);
   }
   

Implementation Patterns

1. Automatic Indexing via Doctrine Events

• Workflow: Configure listeners to sync Doctrine entities to Typesense on postPersist, postUpdate, and postRemove.

  acseo_typesense:
      collections:
          books:
              entity: App\Entity\Book
              fields:
                  id: id
                  title: title
                  author: author
              sync_events: true  # Enables automatic indexing
  

• Custom Mapping: Override field mappings in config or via annotations:

  fields:
      custom_field: [property_path, typesense_field_name]
  

2. Searching Collections

• Basic Search:

  $results = $this->typesense->search('books', 'Laravel', [
      'query_by' => 'title,author',
      'per_page' => 10,
  ]);
  

• Filtered Search:

  $results = $this->typesense->search('books', '', [
      'filter_by' => 'author:"John Doe" AND year:2023',
  ]);
  

3. Bulk Operations

• Bulk Indexing:

  $this->typesense->bulkIndex('books', $doctrineEntities);
  

• Collection Management:

  $this->typesense->createCollection('books', $schema);
  $this->typesense->deleteCollection('books');
  

4. Integration with Symfony Forms

• Search Form Integration:

  use ACSEO\TypesenseBundle\Form\TypesenseSearchType;
  
  $builder->add('search', TypesenseSearchType::class, [
      'collection' => 'books',
      'query_by' => 'title,author',
  ]);
  

Gotchas and Tips

Pitfalls

1. Collection Prefix Conflicts

   • If collection_prefix is set (e.g., test_), ensure your collection names in config match (e.g., test_books).
   • Fix: Verify config and Typesense dashboard collection names align.

2. Field Mapping Mismatches

   • If fields are misconfigured (e.g., id: non_existent), indexing fails silently.
   • Fix: Validate mappings with:

     $this->typesense->getCollectionSchema('books');
     

3. Doctrine Sync Race Conditions

   • Automatic sync (sync_events: true) may conflict with manual bulk operations.
   • Fix: Disable sync temporarily during bulk ops:

     $this->typesense->disableSync();
     // Bulk operations...
     $this->typesense->enableSync();
     

4. Environment-Specific Config

   • Hardcoding TYPESENSE_URL in config bypasses .env.
   • Fix: Always use %env(resolve:TYPESENSE_URL)% in YAML.

Debugging Tips

• Enable Logging:

  acseo_typesense:
      debug: true  # Logs all Typesense operations to Symfony logger
  

• Validate Schema:

  $schema = $this->typesense->getCollectionSchema('books');
  dump($schema);
  

• Check Indexed Data:

  $documents = $this->typesense->getDocuments('books', ['id:1']);
  dump($documents);
  

Extension Points

1. Custom Transformers

   • Extend ACSEO\TypesenseBundle\Transformer\DoctrineObjectTransformer to handle complex entity-to-document logic.
   • Example:

     class CustomBookTransformer extends DoctrineObjectTransformer
     {
         public function transform($entity, array $fields): array
         {
             $data = parent::transform($entity, $fields);
             $data['formatted_title'] = strtoupper($entity->getTitle());
             return $data;
         }
     }
     

   • Register in services.yaml:

     services:
         App\Transformer\CustomBookTransformer:
             tags: [acseo_typesense.transformer, { alias: 'App\Entity\Book' }]
     

2. Event Listeners

   • Subscribe to TypesenseEvents for pre/post-indexing logic:

     use ACSEO\TypesenseBundle\Event\TypesenseEvent;
     
     $dispatcher->addListener(TypesenseEvent::PRE_INDEX, function (TypesenseEvent $event) {
         $event->setData(['custom_field' => 'value']);
     });
     

3. Async Indexing

   • Use Symfony Messenger to offload indexing:

     $this->messageBus->dispatch(new IndexTypesenseMessage($entity, 'books'));
     

   • Implement IndexTypesenseMessageHandler to process messages asynchronously.