Search Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ibexa/search
   

   Ensure your project uses PHP 8.3+ and Symfony 7+ (or Ibexa DXP 5.x).

2. Configuration:

   • Register the bundle in config/bundles.php:

     Ibexa\SearchBundle\IbexaSearchBundle::class => ['all' => true],
     

   • Configure search engines in config/packages/ibexa_search.yaml:

     ibexa_search:
         search_engines:
             default:
                 engine: ibexa_search_engine_elasticsearch
                 host: '%env(SEARCH_HOST)%'
                 port: '%env(int:SEARCH_PORT)%'
     

3. First Use Case:

   • Basic Search Query:

     use Ibexa\Search\SearchService;
     use Ibexa\Search\Query\Criteria;
     
     $searchService = $this->container->get(SearchService::class);
     $criteria = new Criteria();
     $criteria->query = new \Ibexa\Search\Query\Query();
     $criteria->query->queryString = 'laravel';
     
     $searchResults = $searchService->findContent($criteria);
     

Key Entry Points

• SearchService: Core service for executing searches.
• Criteria: Defines search parameters (query, filters, sorting, etc.).
• Query: Contains the actual search query (e.g., queryString, match, bool).

Implementation Patterns

Common Workflows

1. Searching Content

• Basic Query:

  $criteria = new Criteria();
  $criteria->query = new Query();
  $criteria->query->queryString = 'developer guide';
  $results = $searchService->findContent($criteria);
  

• Filtering by Content Type:

  $criteria->filter = new \Ibexa\Search\Query\Criteria\ContentTypeFilter();
  $criteria->filter->contentTypeIdentifier = 'article';
  

2. Facets (Filtering)

• Add a Facet:

  $criteria->addFacet('language', new \Ibexa\Search\Query\Facet\TermFacet());
  $results = $searchService->findContent($criteria);
  

• Apply a Facet Filter:

  $criteria->filter = new \Ibexa\Search\Query\Criteria\FacetFilter();
  $criteria->filter->facetName = 'language';
  $criteria->filter->facetValue = 'en';
  

3. Sorting Results

$criteria->sortClauses = [
    new \Ibexa\Search\Query\SortClause\FieldSortClause('modified', SortClause::ASCENDING),
];

4. Pagination

$criteria->offset = 0;
$criteria->limit = 10;
$results = $searchService->findContent($criteria);

5. Autocomplete/Suggestions

$suggestionService = $this->container->get(\Ibexa\Search\Suggestion\SuggestionService::class);
$suggestions = $suggestionService->getSuggestions('lar', 5);

6. Spell Check

$spellCheckService = $this->container->get(\Ibexa\Search\SpellCheck\SpellCheckService::class);
$corrections = $spellCheckService->check('laravel', 'en');

Integration Tips

Leveraging Events

• Listen to search events (e.g., SearchEvent::POST_SEARCH) to modify results:

  $eventDispatcher->addListener(SearchEvent::POST_SEARCH, function (SearchEvent $event) {
      $event->getResults()->addMetadata('custom_key', 'custom_value');
  });
  

Custom Search Engines

• Extend the SearchEngine interface to integrate with third-party engines (e.g., Solr, Algolia):

  class CustomSearchEngine implements SearchEngineInterface {
      public function search(Criteria $criteria): SearchResult {
          // Custom logic
      }
  }
  

Repository Integration

• Use SearchRepository for Ibexa-specific content operations:

  $repository = $this->container->get(\Ibexa\Core\Repository\Repository::class);
  $searchService = $repository->getSearchService();
  

Symfony Forms Integration

• Bind search criteria to a form for user input:

  $builder->add('query', TextType::class, [
      'mapped' => false,
  ]);
  

Gotchas and Tips

Pitfalls

1. Deprecation Warnings:

   • Ibexa Search v5+ drops PHP < 8.3 and Symfony < 7.0 support. Ensure compatibility.
   • Avoid class_alias usage (removed in v5).

2. Criteria Building:

   • Date Ranges: Use DateRangeFilter with ISO-8601 formatted strings:

     $filter = new \Ibexa\Search\Query\Criteria\DateRangeFilter();
     $filter->fieldIdentifier = 'modified';
     $filter->rangeStart = '2023-01-01T00:00:00+00:00';
     $filter->rangeEnd = '2023-12-31T23:59:59+00:00';
     $criteria->filter = $filter;
     

   • Partial Word Search: Disabled by default (use match query for exact phrases).

3. Performance:

   • Avoid Wildcards: Queries like lar* are inefficient. Use queryString for full-text search.
   • Facet Limits: Excessive facets slow down queries. Limit with:

     $facet->setLimit(10);
     

4. Content Type Mismatches:

   • Ensure contentTypeIdentifier matches your Ibexa content type definitions.

5. Spell Check Limitations:

   • Requires a configured spell-check dictionary (e.g., en for English).

Debugging Tips

1. Log Criteria:

   $logger->info('Search Criteria:', [
       'query' => $criteria->query->queryString,
       'filters' => $criteria->filter,
   ]);
   

2. Check Search Engine Status:

   • Verify Elasticsearch/Solr connectivity via:

     $searchService->getSearchEngine()->ping();
     

3. Use SearchResult Metadata:

   • Inspect raw results for debugging:

     foreach ($results->getSearchHits() as $hit) {
         $logger->info('Hit ID:', $hit->getValue('id'));
     }
     

Extension Points

1. Custom Data Mappers:

   • Implement PagerSearchDataMapperInterface to transform search hits into custom objects:

     class CustomDataMapper implements PagerSearchDataMapperInterface {
         public function mapSearchResult(SearchResult $searchResult): array {
             return [
                 'id' => $searchResult->getValue('id'),
                 'title' => $searchResult->getValue('title'),
             ];
         }
     }
     

2. Query Builders:

   • Extend QueryBuilder to add domain-specific logic:

     class ArticleQueryBuilder extends QueryBuilder {
         public function forPublishedArticles(): self {
             $this->query->queryString = 'is_published:true';
             return $this;
         }
     }
     

3. Search Event Subscribers:

   • Modify results dynamically:

     $eventDispatcher->addSubscriber(new class implements EventSubscriberInterface {
         public function getSubscribedEvents(): array {
             return [SearchEvent::POST_SEARCH];
         }
         public function onPostSearch(SearchEvent $event) {
             $event->getResults()->setTotalCount($event->getResults()->getTotalCount() * 2);
         }
     });
     

4. Configuration Overrides:

   • Override default search engine settings in config/packages/ibexa_search.yaml:

     ibexa_search:
         search_engines:
             default:
                 engine: ibexa_search_engine_elasticsearch
                 host: 'localhost'
                 port: 9200
                 index_name: 'custom_index'
     

Pro Tips

1. Use SearchService Directly:

   • Avoid coupling to Ibexa’s Repository unless necessary. SearchService is more flexible.

2. Leverage SearchResult:

   • Access metadata, facets, and raw hits:

     $facets = $results->getFacets();
     $total