Search Laravel Package

Getting Started

Minimal Steps to First Query

1. Installation

   composer require minimalcode/search
   

   Ensure sorl/pecl-solr is installed in your PHP environment.

2. Basic Setup

   • Require the autoloader:

     require __DIR__ . '/vendor/autoload.php';
     

   • Initialize the criteria builder:

     use MinimalCode\Search\Criteria;
     $criteria = new Criteria();
     

3. First Use Case: Simple Search

   $query = $criteria
       ->addField('title', 'Laravel')
       ->addField('description', 'PHP Framework')
       ->getQuery();
   

   Use $query with Sorl\Lucene to execute the search.

4. Where to Look First

   • Wiki Documentation for API reference.
   • src/MinimalCode/Search/Criteria.php for core logic and available methods.

Implementation Patterns

Fluent Query Construction

Leverage method chaining for readability and maintainability:

$query = (new Criteria())
    ->addField('author', 'Taylor Otwell')
    ->addField('tags', 'laravel,php')
    ->addBoost('title', 2.0)
    ->addRange('price', 10, 100)
    ->getQuery();

Common Workflows

1. Dynamic Field Filtering

   $fields = ['title', 'content', 'tags'];
   $criteria = new Criteria();
   foreach ($fields as $field) {
       $criteria->addField($field, $searchTerm);
   }
   

2. Geospatial Queries

   $criteria
       ->addGeoDistance('location', '37.7749,-122.4194', 5, 'km')
       ->addGeoFilter('location', '37.7749,-122.4194', 10, 'km');
   

3. Faceted Search Combine with Sorl\Lucene’s faceting:

   $query = $criteria->addField('category', 'books')->getQuery();
   $results = $solr->query($query)->getFacet('category');
   

4. Integration with Laravel Use in a service layer or repository:

   class SearchService {
       public function search(string $query, array $fields): string {
           $criteria = new Criteria();
           foreach ($fields as $field) {
               $criteria->addField($field, $query);
           }
           return $criteria->getQuery();
       }
   }
   

Integration Tips

• Cache Queries: Store generated queries in Laravel’s cache for repeated searches.
• Validation: Validate input fields before passing them to addField() to avoid injection.
• Logging: Log generated queries for debugging:

  \Log::debug('Solr Query:', ['query' => $criteria->getQuery()]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Sorl Version

   • The package was last updated in 2017 and assumes Sorl\Lucene (not SolrCloud or newer APIs).
   • Workaround: Use a compatible Sorl version or wrap the package in a compatibility layer.

2. Geodist Bug

   • Fixed in 1.0.1, but negative geodist values may still cause issues.
   • Tip: Validate distance values before passing to addGeoDistance().

3. No SolrCloud Support

   • The package is designed for single-node Sorl\Lucene, not distributed SolrCloud.
   • Tip: Use a proxy layer (e.g., HAProxy) if scaling horizontally.

4. Limited Error Handling

   • The package throws generic exceptions. Wrap usage in try-catch:

     try {
         $query = $criteria->addField('invalid_field', 'value')->getQuery();
     } catch (\Exception $e) {
         \Log::error('Search Criteria Error:', ['error' => $e->getMessage()]);
         return null;
     }
     

Debugging

• Validate Queries: Use Sorl’s admin UI to test raw queries.
• Enable Sorl Logging:

  $solr->setLogger(new \Monolog\Logger('solr'));
  

Extension Points

1. Custom Operators Extend the Criteria class to add custom Lucene operators:

   class ExtendedCriteria extends Criteria {
       public function addCustomOperator(string $field, string $operator, string $value): self {
           $this->query .= " {$field}{$operator}\"{$value}\"";
           return $this;
       }
   }
   

2. Field Normalization Preprocess fields before adding them to the query:

   $criteria->addField('normalized_' . strtolower($field), $value);
   

3. Plugin Integration Combine with Laravel Scout or other search packages as a query builder:

   public function toScoutQueryBuilder($query) {
       return $query->where('solr_query', $this->criteria->getQuery());
   }
   

Configuration Quirks

• Default Boost: The package uses a default boost of 1.0. Explicitly set boosts for critical fields.
• Field Aliases: Sorl may require field aliases (e.g., text vs. text_en). Configure these in your schema.xml.

Performance Tips

• Field Selection: Limit fields in queries to reduce overhead.
• Query Caching: Cache frequent queries (e.g., navigation filters):

  $cacheKey = md5($criteria->getQuery());
  $cachedQuery = \Cache::get($cacheKey);