Sphinx Realtime Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require acts/sphinx-realtime-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Acts\SphinxRealtimeBundle\ActsSphinxRealtimeBundle::class => ['all' => true],
   ];
   

2. Configuration Define Sphinx connection in config/packages/acts_sphinx_realtime.yaml:

   acts_sphinx_realtime:
       client:
           host: '127.0.0.1'
           port: 9312
           path: '/var/run/sphinxsearch/sphinx.sock' # Optional Unix socket
       indexer:
           index_name: 'your_index_name'
           delta_index_name: 'your_delta_index_name'
   

3. First Use Case Annotate a Doctrine entity to enable real-time indexing:

   use Acts\SphinxRealtimeBundle\Annotation\SphinxRealtime;
   
   /**
    * @SphinxRealtime(
    *     index="your_index_name",
    *     deltaIndex="your_delta_index_name",
    *     attributes={
    *         "id", "title", "content"
    *     }
    * )
    */
   class Article
   {
       // ...
   }
   

4. Trigger Initial Sync Run the command to populate the index:

   php bin/console acts:sphinx:realtime:sync
   

Implementation Patterns

Workflow Integration

1. Entity Lifecycle Hooks Leverage Doctrine lifecycle events (prePersist, preUpdate, preRemove) to auto-sync changes:

   use Acts\SphinxRealtimeBundle\Event\SphinxRealtimeEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class SphinxSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               SphinxRealtimeEvent::PRE_PERSIST,
               SphinxRealtimeEvent::PRE_UPDATE,
               SphinxRealtimeEvent::PRE_REMOVE,
           ];
       }
   
       public function onPrePersist(SphinxRealtimeEvent $event)
       {
           $event->getEntityManager()->flush(); // Force sync
       }
   }
   

2. Bulk Operations Use the sync command for batch updates (e.g., after migrations):

   php bin/console acts:sphinx:realtime:sync --entity=Article --limit=1000
   

3. Querying with Sphinx Integrate with a Sphinx client (e.g., SphinxQL) for searches:

   use SphinxQL\Client;
   
   $client = new Client('unix:///var/run/sphinxsearch/sphinx.sock');
   $results = $client->query('SELECT * FROM your_index_name WHERE MATCH(\'@title keyword\')');
   

4. Custom Indexing Logic Override default behavior via a custom Indexer service:

   # config/services.yaml
   services:
       App\Service\CustomSphinxIndexer:
           arguments:
               - '@acts_sphinx_realtime.indexer'
           tags: ['acts_sphinx_realtime.indexer']
   

Gotchas and Tips

Common Pitfalls

1. Delta Index Mismatch

   • Ensure delta_index_name in annotations matches the config. Mismatches cause silent failures.
   • Fix: Validate with php bin/console debug:container acts_sphinx_realtime.indexer.

2. Attribute Mapping Issues

   • Sphinx requires attributes to be defined in the schema (sphinx.conf). Missing attributes throw SphinxException.
   • Tip: Use acts:sphinx:realtime:schema:dump to verify schema alignment.

3. Performance Bottlenecks

   • Real-time indexing triggers on every flush(). For high-traffic apps, batch updates:

     $em->getConnection()->getConfiguration()->setSQLLogger(null); // Disable logging
     $em->flush(); // Sync in bulk
     

4. Event Dispatching Order

   • Sphinx events fire before Doctrine events. Override cautiously to avoid infinite loops:

     // Avoid this anti-pattern:
     $event->getEntityManager()->persist($event->getEntity()); // Recursive sync!
     

Debugging Tips

1. Enable Verbose Logging

   # config/packages/monolog.yaml
   handlers:
       sphinx:
           type: stream
           path: "%kernel.logs_dir%/sphinx.log"
           level: debug
           channels: ["acts_sphinx"]
   

2. Check Index Status

   php bin/console acts:sphinx:realtime:status
   

3. Schema Validation Compare your sphinx.conf with the generated schema:

   php bin/console acts:sphinx:realtime:schema:dump > schema.sql
   

Extension Points

1. Custom Indexers Implement Acts\SphinxRealtimeBundle\Indexer\IndexerInterface for non-Doctrine data sources.

2. Event Listeners Extend SphinxRealtimeEvent to add pre/post-processing:

   $event->setData(['custom_field' => $value]); // Inject dynamic data
   

3. Async Indexing Offload sync to a queue (e.g., Symfony Messenger) for large datasets:

   use Symfony\Component\Messenger\MessageBusInterface;
   
   class AsyncSphinxSync
   {
       public function __construct(private MessageBusInterface $bus) {}
   
       public function sync(EntityManagerInterface $em, string $entityClass)
       {
           $this->bus->dispatch(new SyncSphinxMessage($em, $entityClass));
       }
   }