Sphinxsearch Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require alkhvalko/sphinxsearch-bundle
   

   (Note: The README references iakumai/sphinxsearch-bundle, but the package is actually alkhvalko/sphinxsearch-bundle per composer.json.)

2. Register the Bundle Add to config/bundles.php (Symfony 4+):

   IAkumaI\SphinxsearchBundle\SphinxsearchBundle::class => ['all' => true],
   

3. Configure Sphinx Connection Add to config/packages/sphinxsearch.yaml:

   sphinxsearch:
       searchd:
           host: localhost
           port: 9312
       indexes:
           your_index_name: "App\Entity\YourEntity"
   

4. First Search Query Inject the service in a controller:

   use IAkumaI\SphinxsearchBundle\Search\Sphinxsearch;
   
   public function searchAction(Request $request, Sphinxsearch $sphinx)
   {
       $results = $sphinx->search($request->query->get('q'), ['your_index_name']);
       return $this->render('search/results.html.twig', ['results' => $results]);
   }
   

Implementation Patterns

Core Workflows

1. Basic Search Use search() for simple queries:

   $results = $sphinx->search('query', ['index1', 'index2']);
   

   • Returns raw Sphinx results (IDs, weights, attributes).

2. Entity Conversion Use searchEx() with configured indexes to auto-hydrate entities:

   $results = $sphinx->searchEx('query', 'index_name');
   // $results['matches'][id]['entity'] contains the Doctrine entity.
   

3. Filtering Apply filters before searching:

   $sphinx->setFilter('category_id', 5); // Exact match
   $sphinx->setFilterRange('price', 10, 100); // Range filter
   $sphinx->setFilterBetweenDates('created_at', $startDate, $endDate);
   

4. Pagination with Pagerfanta

   $adapter = new \IAkumaI\SphinxsearchBundle\Pagerfanta\Adapter\SphinxSearchAdapter(
       $sphinx,
       'query',
       'index_name',
       ['max_results' => 1000]
   );
   $pager = new Pagerfanta($adapter);
   

5. Highlighting in Twig

   {{ result.content|sphinx_highlight('index_name', 'query') }}
   

Integration Tips

• Doctrine Bridge: Enable entity hydration by setting the Doctrine bridge:

  $sphinx->setBridge($this->get('iakumai.sphinxsearch.doctrine.bridge'));
  

• Custom Attributes: Map Sphinx attributes to Doctrine fields in your sphinx.conf:

  sql_attr_uint = entity_id
  sql_attr_timestamp = updated_at
  

• Multi-Index Queries: Use searchEx() with an array of index names for cross-index searches.

Gotchas and Tips

Pitfalls

1. Index Configuration Mismatch

   • Ensure indexes in config.yml match your sphinx.conf sources.
   • Example: If sphinx.conf defines source Example, your config must reference the corresponding index name (e.g., index Example).

2. Entity Hydration Requirements

   • For searchEx(), your Sphinx index must include an index_name attribute if querying multiple indexes.
   • Example sql_query in sphinx.conf:

     sql_query = SELECT ..., 'index_name' as index_name FROM table
     

3. Date Filtering Quirks

   • setFilterBetweenDates() expects DateTime objects or timestamps. Invalid formats (e.g., d.m.Y) will fail silently.

4. Pagerfanta Adapter Caveats

   • Always set the Doctrine bridge ($sphinx->setBridge()) before using the adapter.
   • Pagination limits (max_results) must be set to avoid performance issues.

5. Deprecated Methods

   • The bundle uses the older romainneutron/Sphinx-Search-API-PHP-Client. Some methods (e.g., BuildExcerpts) may behave differently than the newer sphinxsearch/sphinxapi package.

Debugging Tips

• Connection Issues: Check Sphinx daemon status (netstat -tulnp | grep 9312) and verify host/port in config.
• Empty Results: Use setLimits(0, 100) to debug if results are being filtered out.
• Entity Hydration Failures: Ensure your Doctrine entity has a getId() method and matches the Sphinx id attribute.

Extension Points

1. Custom Search Logic Override the default service class by configuring iakumai.sphinxsearch.search.class in config/packages/sphinxsearch.yaml:

   sphinxsearch:
       search:
           class: App\Service\CustomSphinxSearch
   

2. Doctrine Bridge Extensions Implement IAkumaI\SphinxsearchBundle\Doctrine\BridgeInterface for custom entity hydration:

   class CustomBridge implements BridgeInterface {
       public function hydrate(array $match, string $indexName) {
           // Custom logic here
       }
   }
   

3. Twig Filters Extend the sphinx_highlight filter by overriding the bundle’s Twig extension.

Performance Tips

• Batch Indexing: Use Sphinx’s sql_range_step for large datasets to avoid timeouts.
• Caching: Cache frequent queries (e.g., with Symfony’s cache system) if Sphinx isn’t the bottleneck.
• Attribute Indexing: Pre-index frequently filtered attributes (e.g., category_id) for faster queries.