Zendsearch Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require nqxcode/zendsearch
   

   Add to config/app.php under providers:

   Nqxcode\ZendSearch\ZendSearchServiceProvider::class,
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Nqxcode\ZendSearch\ZendSearchServiceProvider"
   

   Edit config/zendsearch.php to define your ZendSearch index paths and settings.

3. First Use Case: Indexing a Model

   use Nqxcode\ZendSearch\ZendSearch;
   
   // Index a model (e.g., Article)
   ZendSearch::index('articles', [
       'id' => $article->id,
       'title' => $article->title,
       'content' => $article->body,
   ]);
   

4. Searching

   $results = ZendSearch::search('articles', 'laravel');
   

Implementation Patterns

Workflows

1. Model Observers for Auto-Indexing Use Laravel's Observers to index models on saved/created events:

   // app/Observers/ArticleObserver.php
   public function saved(Article $article)
   {
       ZendSearch::index('articles', $article->toSearchArray());
   }
   

2. Batch Indexing For bulk operations (e.g., migrations or imports):

   $articles = Article::all();
   foreach ($articles as $article) {
       ZendSearch::index('articles', $article->toSearchArray());
   }
   

3. Searching with Filters

   $results = ZendSearch::search('articles', 'laravel', [
       'filters' => [
           'category' => 'tutorial',
           'published' => true,
       ],
   ]);
   

4. Paginated Results

   $results = ZendSearch::search('articles', 'laravel', [
       'offset' => 0,
       'limit' => 10,
   ]);
   

Integration Tips

• Laravel Scout Alternative: Use this package as a lightweight alternative to Scout for simple text search.
• Hybrid Search: Combine with Laravel's query builder for complex queries (e.g., filter by published_at in DB, then search text in ZendSearch).
• Caching: Cache search results if your data is static or updates infrequently:

  $cacheKey = "search:articles:{$query}";
  $results = Cache::remember($cacheKey, now()->addHours(1), function () use ($query) {
      return ZendSearch::search('articles', $query);
  });
  

Gotchas and Tips

Pitfalls

1. Index Paths

   • Ensure the index_path in config/zendsearch.php is writable by the web server.
   • Default paths (e.g., storage/zendsearch) may not exist; create them manually:

     mkdir -p storage/zendsearch/{articles,data}
     

2. Case Sensitivity

   • ZendSearch is case-sensitive by default. Use ZendSearch::setCaseSensitive(false) globally or per search:

     ZendSearch::search('articles', 'Laravel', ['case_sensitive' => false]);
     

3. Memory Limits

   • Large indexes may hit PHP memory limits. Optimize with smaller batches or increase memory_limit in php.ini.

4. No Full-Text Analyzer

   • Unlike Elasticsearch, ZendSearch lacks advanced full-text analysis (stemming, stopwords). Preprocess text if needed:

     $cleanText = strtolower(preg_replace('/[^a-z0-9\s]/', '', $article->body));
     

5. No Native Highlighting

   • Highlighting requires manual implementation (e.g., regex or custom logic).

Debugging

• Check Index Existence:

  if (!ZendSearch::indexExists('articles')) {
      ZendSearch::createIndex('articles');
  }
  

• Verify Indexed Data:

  $index = ZendSearch::getIndex('articles');
  dump($index->getDocuments());
  

• Logs: Enable debug mode in config/zendsearch.php to log queries:

  'debug' => env('ZENDSEARCH_DEBUG', false),
  

Extension Points

1. Custom Scoring Override the default scoring logic by extending the Nqxcode\ZendSearch\Search class:

   class CustomSearch extends \Nqxcode\ZendSearch\Search {
       protected function scoreDocument($document, $query) {
           // Custom scoring logic
       }
   }
   

   Bind it in the service provider.

2. Add Fields Dynamically Extend the Nqxcode\ZendSearch\Index class to support dynamic fields:

   $index->addField('dynamic_field', \ZendSearch\Field::TEXT);
   

3. Async Indexing Use Laravel Queues to offload indexing:

   // Dispatch a job
   IndexArticleJob::dispatch($article);
   
   // Job class
   public function handle() {
       ZendSearch::index('articles', $this->article->toSearchArray());
   }
   

4. Multi-Index Search Combine results from multiple indexes:

   $results = array_merge(
       ZendSearch::search('articles', $query),
       ZendSearch::search('products', $query)
   );