Search Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chebur/search-bundle
   

   Enable the bundle in config/bundles.php (Symfony) or AppKernel.php (legacy):

   Chebur\SearchBundle\CheburSearchBundle::class => ['all' => true],
   

2. First Use Case: Define a searchable entity (e.g., Product) with annotations:

   use Chebur\SearchBundle\Annotation\Searchable;
   use Chebur\SearchBundle\Annotation\SearchField;
   
   /**
    * @Searchable
    */
   class Product
   {
       /**
        * @SearchField(type="text")
        */
       private $name;
   
       /**
        * @SearchField(type="number")
        */
       private $price;
   }
   

3. Basic Search Query:

   use Chebur\SearchBundle\Search\SearchQuery;
   
   $query = new SearchQuery(Product::class);
   $query->addFilter('name', 'laptop'); // Text search
   $query->addFilter('price', ['min' => 500, 'max' => 1000]); // Range filter
   
   $results = $query->execute();
   

Implementation Patterns

Core Workflows

1. Search Query Construction:

   • Use SearchQuery builder for dynamic queries:

     $query = (new SearchQuery(Product::class))
         ->setPage(2)
         ->setLimit(10)
         ->addSort('price', 'desc');
     

   • Chain methods for readability (fluent interface).

2. Pagination:

   • Built-in pagination via setPage()/setLimit().
   • Retrieve paginated results:

     $results = $query->execute(); // Returns array of entities + metadata
     $totalItems = $results['metadata']['total'];
     

3. Filtering:

   • Text: addFilter('field', 'term') (partial matches).
   • Range: addFilter('field', ['min' => X, 'max' => Y]).
   • Exact: addFilter('field', ['exact' => 'value']).
   • Multi-value: addFilter('tags', ['in' => ['php', 'laravel']]).

4. Sorting:

   $query->addSort('created_at', 'desc');
   $query->addSort('name', 'asc');
   

5. Integration with Controllers:

   public function search(Request $request)
   {
       $query = new SearchQuery(Product::class);
       $query->addFilter('name', $request->get('q'));
       $query->addSort('name', 'asc');
   
       $results = $query->execute();
       return view('products.index', compact('results'));
   }
   

6. Form Integration:

   • Use Symfony forms to bind search parameters:

     $form = $this->createFormBuilder()
         ->add('q', TextType::class, ['label' => 'Search'])
         ->add('price_min', NumberType::class)
         ->add('price_max', NumberType::class)
         ->getForm();
     

Gotchas and Tips

Pitfalls

1. Annotation Caching:

   • After adding @Searchable or @SearchField, clear cache:

     php bin/console cache:clear
     

   • Use php bin/console chebur:search:debug to validate annotations.

2. Case Sensitivity:

   • Text searches are case-insensitive by default. Override in config:

     # config/packages/chebur_search.yaml
     chebur_search:
         default_search_options:
             case_sensitive: true
     

3. Performance:

   • Avoid complex queries on large datasets without indexing. Consider:
     • Database-level indexing (e.g., PostgreSQL tsvector).
     • Caching frequent queries (e.g., Symfony\Contracts\Cache\CacheInterface).

4. Field Type Mismatches:

   • Ensure @SearchField(type="...") matches the actual field type (e.g., text, number, date).
   • Debug with:

     php bin/console chebur:search:debug Product
     

5. Pagination Offsets:

   • Large setLimit() + setPage() values may cause timeouts. Optimize with:

     $query->setLimit(50); // Max recommended
     

Debugging Tips

1. Query Logging: Enable SQL logging in .env:

   APP_DEBUG=true
   DATABASE_LOG_QUERIES=true
   

2. Validate Annotations:

   php bin/console chebur:search:debug EntityName
   

3. Check Config: Override defaults in config/packages/chebur_search.yaml:

   chebur_search:
       default_search_options:
           limit: 20
           page: 1
   

Extension Points

1. Custom Field Types: Extend Chebur\SearchBundle\Search\FieldType\AbstractFieldType for custom logic (e.g., geospatial).

2. Query Builders: Override Chebur\SearchBundle\Search\QueryBuilder for database-specific optimizations.

3. Event Listeners: Listen to chebur.search.query events to modify queries dynamically:

   use Chebur\SearchBundle\Event\SearchQueryEvent;
   
   $dispatcher->addListener(SearchQueryEvent::class, function (SearchQueryEvent $event) {
       $event->getQuery()->addFilter('active', true);
   });
   

4. Result Transformers: Use Chebur\SearchBundle\Search\ResultTransformerInterface to alter returned data:

   $query->setTransformer(new CustomTransformer());