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
   

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
   

4. First Use Case Inject the TypesenseSearchService and search:

   use ACSEO\TypesenseBundle\Service\TypesenseSearchService;
   
   public function searchBooks(TypesenseSearchService $searchService)
   {
       $results = $searchService->search('books', 'query');
       return $this->json($results);
   }
   

Implementation Patterns

Core Workflows

1. Automatic Indexing

   • Configure Doctrine listeners via acseo_typesense.yml:

     collections:
         books:
             entity: App\Entity\Book
             auto_index: true  # Auto-index on Doctrine events
     

   • Events triggered: prePersist, preUpdate, preRemove.

2. Manual Indexing

   $searchService->indexEntity($bookEntity);
   $searchService->deleteIndexedEntity($bookEntity);
   

3. Custom Field Mapping

   collections:
       books:
           entity: App\Entity\Book
           fields:
               id: id
               title: title
               author: author.name  # Nested property
               published_at: publishedAt
   

4. Search with Filters

   $results = $searchService->search(
       'books',
       'query',
       ['filter_by': 'published_at:[1900-01-01 TO NOW]']
   );
   

5. Pagination

   $results = $searchService->search('books', 'query', [], 10, 0); // limit, offset
   

Integration Tips

• Symfony Forms: Use ACSEO\TypesenseBundle\Form\TypesenseType for search-as-you-type fields.
• API Platform: Extend TypesenseSearchService to integrate with ApiPlatform\Metadata\Operation.
• Event Subscribers: Override default indexing logic via TypesenseIndexEvent listeners.

Gotchas and Tips

Pitfalls

1. Collection Naming Conflicts

   • Ensure collection_prefix in config avoids clashes with existing Typesense collections.
   • Example: collection_prefix: 'app_' → Collection names become app_books.

2. Field Mapping Errors

   • Undefined properties in fields will throw exceptions. Validate with:

     $this->get('validator')->validate($entity, ['Typesense']);
     

3. Auto-Indexing Overhead

   • Disable auto_index for large entities or use @Typesense\Ignore annotations:

     use ACSEO\TypesenseBundle\Annotation\Typesense;
     /**
      * @Typesense\Ignore()
      */
     private $sensitiveData;
     

4. Rate Limiting

   • Typesense may throttle requests. Use retry_after in responses to implement exponential backoff.

Debugging

• Log Queries: Enable debug mode in acseo_typesense.yml:

  debug: true
  

• Check Indexed Data: Use the TypesenseAdminService to inspect collections:

  $adminService->getCollection('books');
  

Extension Points

1. Custom Transformers Override ACSEO\TypesenseBundle\Transformer\DoctrineTransformer to handle complex types (e.g., JSON fields):

   $transformer = $this->get('acseo_typesense.transformer.doctrine');
   $transformer->addCustomField('App\Entity\Book', 'tags', function ($book) {
       return json_encode($book->getTags());
   });
   

2. Event Listeners Extend indexing logic via TypesenseIndexEvent:

   public function onIndex(TypesenseIndexEvent $event) {
       $event->setData(['custom_field' => 'value']);
   }
   

3. Async Indexing Use Symfony Messenger to queue indexing tasks for performance:

   acseo_typesense:
       async: true