Sphinx Realtime Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Symfony2 project via Composer:

   composer require camdram/sphinx-realtime-bundle
   

   Enable the bundle in app/AppKernel.php:

   new Camdram\SphinxRealtimeBundle\CamdramSphinxRealtimeBundle(),
   

2. Configuration Configure Sphinx connection in app/config/config.yml:

   sphinx_realtime:
       client:
           host: 127.0.0.1
           port: 9312
           path: /var/run/sphinx/sphinx.sock  # Optional, for Unix sockets
       index: your_index_name
   

3. First Use Case: Indexing an Entity Annotate your Doctrine entity with @Sphinx\Index:

   use Camdram\SphinxRealtimeBundle\Bridge\Doctrine\Sphinx\Index;
   
   /**
    * @Index(index="your_index_name", delta="your_delta_name")
    */
   class Product
   {
       // ...
   }
   

   Run the initial sync:

   php app/console sphinx:realtime:sync
   

Implementation Patterns

Workflows

1. Automatic Sync The bundle hooks into Doctrine lifecycle events (postPersist, postUpdate, postRemove) to auto-sync entities. No manual intervention required for CRUD operations.

2. Delta Indexing Use delta indexes for real-time updates:

   # app/config/config.yml
   sphinx_realtime:
       client:
           host: 127.0.0.1
       index: main_index
       delta_index: delta_index  # Optional delta config
   

3. Custom Mappings Override default field mappings via annotations:

   /**
    * @Index(
    *     fields={
    *         "name"="title",
    *         "description"="content"
    *     }
    * )
   */
   class Article { ... }
   

4. Querying Use the SphinxRealtimeClient service to query:

   $client = $this->get('sphinx_realtime.client');
   $results = $client->query('search_term');
   

Integration Tips

• Event Listeners: Extend sync logic by subscribing to sphinx.realtime.sync events.
• Batch Sync: For large datasets, use php app/console sphinx:realtime:sync --batch-size=100.
• Doctrine Events: Disable auto-sync for bulk operations:

  $em->getEventManager()->removeEventListeners('postPersist');
  

Gotchas and Tips

Pitfalls

1. Delta Index Mismatch Ensure delta_index in config matches the @Index(delta="...") annotation. Mismatches cause silent failures.

2. Connection Issues Sphinx client may hang if the server is unreachable. Add retry logic:

   sphinx_realtime:
       client:
           timeout: 5
           retries: 3
   

3. Field Type Conflicts Sphinx expects specific field types (e.g., INT64 for IDs). Annotate explicitly:

   /**
    * @Index(fields={
    *     "id"="id INT64"
    * })
    */
   

4. Circular References Avoid bidirectional associations in indexed entities to prevent infinite loops during sync.

Debugging

• Enable Logging: Add to config.yml:

  sphinx_realtime:
      debug: true
  

  Logs appear in var/log/dev.log.

• Check Sync Status:

  php app/console sphinx:realtime:status
  

Extension Points

1. Custom Sync Logic Override the Camdram\SphinxRealtimeBundle\Sync\SyncManager service to add pre/post-sync hooks.

2. Custom Field Transformers Implement Camdram\SphinxRealtimeBundle\Sync\FieldTransformerInterface for custom field formatting.

3. Async Sync Use Symfony’s Messenger component to queue syncs for high-traffic apps:

   sphinx_realtime:
       async: true