Search Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require beecms/search-bundle
   

   Ensure BeeCMS\SearchBundle\BeeCMSSearchBundle is registered in config/bundles.php.

2. Initial Setup Run the setup command to initialize the search system (creates default file-based or DB-backed index):

   php bin/console search:setup
   

   • For file-based search (default), no additional steps are needed.
   • For DB-backed search, the command generates migration files and tables.

3. First Use Case: Basic Search Inject the SearchService into a controller or service:

   use BeeCMS\SearchBundle\Service\SearchService;
   
   class MyController extends AbstractController {
       public function search(SearchService $searchService) {
           $results = $searchService->search('query');
           return $this->json($results);
       }
   }
   

   • File-based search: Scans files in the configured directory (default: var/search/).
   • DB-backed search: Uses the generated tables for indexed queries.

Implementation Patterns

Core Workflows

1. Indexing Content

   • File-based: Automatically scans files in var/search/ (configurable via search.yml).

     # config/packages/bee_cms_search.yaml
     bee_cms_search:
         indexer:
             type: file
             directory: '%kernel.project_dir%/var/search'
     

   • DB-backed: Use search:generate-index to rebuild the index:

     php bin/console search:generate-index
     

     • Triggered manually or via a cron job for periodic updates.

2. Querying

   • Basic Search:

     $results = $searchService->search('laravel');
     

   • Filtered Search (if supported):

     $results = $searchService->search('laravel', ['type' => 'article']);
     

   • Paginated Results:

     $results = $searchService->search('laravel', [], 1, 10); // Page 1, 10 items
     

3. Integration with Laravel

   • Service Container: Bind the SearchService to a custom interface for loose coupling:

     $container->bind(MySearchInterface::class, SearchService::class);
     

   • Events: Listen for search.indexing or search.indexed events to hook into indexing logic:

     $eventDispatcher->addListener('search.indexed', function ($event) {
         // Post-indexing logic (e.g., log, notify)
     });
     

4. Caching

   • Enable caching for file-based searches in search.yml:

     bee_cms_search:
         cache:
             enabled: true
             provider: cache.app
     

   • Clear cache manually:

     php bin/console cache:clear
     

Gotchas and Tips

Pitfalls

1. Indexing Overhead

   • DB-backed: search:generate-index can be resource-intensive for large datasets. Run during low-traffic periods.
   • File-based: Large directories may slow down searches. Use cache.enabled: true to mitigate.

2. Configuration Conflicts

   • Ensure search.yml is merged correctly. Override defaults in config/packages/bee_cms_search.yaml:

     bee_cms_search:
         indexer:
             type: db  # Force DB-backed search
     

   • Symfony 5+: Use imports in config/packages/bee_cms_search.yaml if the bundle doesn’t auto-configure:

     imports:
         - { resource: "@BeeCMSSearchBundle/Resources/config/services.yaml" }
     

3. File Permissions

   • File-based search requires write access to var/search/. Set permissions:

     chmod -R 755 var/search
     

4. Migration Issues

   • If search:setup fails, manually create the DB tables using the generated migration:

     php bin/console doctrine:migrations:migrate
     

Debugging

• Log Indexing: Enable debug mode to log indexed files:

  bee_cms_search:
      debug: true
  

• Check Indexed Data: Inspect the DB table search_index (for DB-backed) or files in var/search/ (for file-based).

Extension Points

1. Custom Indexers Override the default indexer by implementing BeeCMS\SearchBundle\Indexer\IndexerInterface and configure it in search.yml:

   bee_cms_search:
       indexer:
           class: App\CustomIndexer
   

2. Query Modifiers Extend the SearchService to add custom query logic:

   class ExtendedSearchService extends SearchService {
       public function advancedSearch(string $query, array $filters = []) {
           // Custom logic
           return $this->search($query, $filters);
       }
   }
   

   Bind it in services.yaml:

   services:
       App\Service\ExtendedSearchService: '@BeeCMS\SearchBundle\Service\SearchService'
   

3. REST API Monitor the repo for the upcoming REST API module. Until then, wrap the SearchService in a custom API controller:

   class SearchApiController extends AbstractController {
       public function __invoke(SearchService $searchService, Request $request) {
           $query = $request->query->get('q');
           return $this->json($searchService->search($query));
       }
   }
   

   Route it in routes.yaml:

   search:
       path: /api/search
       controller: App\Controller\SearchApiController
       methods: GET