Zendsearch Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require diszo2009/zendsearch
   

   Ensure ext-zendsearch PHP extension is enabled in php.ini.

2. Basic Usage Initialize the ZendSearch engine in a service provider (e.g., AppServiceProvider):

   use Diszo2009\ZendSearch\ZendSearch;
   
   public function register()
   {
       $this->app->singleton('zendsearch', function ($app) {
           return new ZendSearch($app['config']['zendsearch.path']);
       });
   }
   

3. First Use Case: Indexing Documents

   $zendSearch = app('zendsearch');
   $zendSearch->addDocument('doc1', ['title' => 'Laravel', 'content' => 'A PHP framework...']);
   $zendSearch->commit();
   

4. Searching

   $results = $zendSearch->search('framework', ['fields' => ['title', 'content']]);
   

Implementation Patterns

Workflows

1. Indexing Workflow

   • Batch Indexing: Loop through Eloquent models and index them:

     foreach (Post::all() as $post) {
         $zendSearch->addDocument("post_{$post->id}", [
             'title' => $post->title,
             'content' => $post->body,
         ]);
     }
     $zendSearch->commit();
     

   • Incremental Updates: Use updateDocument() for modified records.

2. Search Integration

   • Middleware: Add search to API routes:

     Route::get('/search', function () {
         $query = request('q');
         $results = app('zendsearch')->search($query);
         return response()->json($results);
     });
     

   • Query Builder: Extend Laravel’s query builder with search:

     // In a trait or service
     public function scopeSearch($query, $searchTerm)
     {
         $results = app('zendsearch')->search($searchTerm);
         return $query->whereIn('id', array_map(fn($r) => $r['id'], $results));
     }
     

3. Hybrid Search Combine with database queries for relevance tuning:

   $zendResults = app('zendsearch')->search($query, ['sort' => 'rank']);
   $dbResults = Post::whereIn('id', array_column($zendResults, 'id'))->get();
   

Integration Tips

• Configuration: Centralize paths in config/zendsearch.php:

  return [
      'path' => storage_path('app/zendsearch'),
  ];
  

• Events: Dispatch events after indexing/searching for side effects (e.g., analytics):

  event(new SearchPerformed($query, $results));
  

• Caching: Cache frequent search results in Redis:

  $cacheKey = "search_{$query}";
  $results = cache()->remember($cacheKey, now()->addHours(1), function () use ($query) {
      return app('zendsearch')->search($query);
  });
  

Gotchas and Tips

Pitfalls

1. Path Permissions

   • Ensure the index directory (config['zendsearch.path']) is writable:

     chmod -R 775 storage/app/zendsearch
     

   • Symlink Fix: If using Docker, bind-mount the host directory to avoid permission issues.

2. Memory Limits

   • Large indexes may hit PHP’s memory_limit. Increase it temporarily:

     ini_set('memory_limit', '512M');
     

   • Workaround: Use addDocument() in chunks for massive datasets.

3. Case Sensitivity

   • ZendSearch is case-sensitive by default. Normalize queries:

     $query = strtolower(request('q'));
     

4. Field Mapping

   • ZendSearch requires explicit field definitions. Omit fields to exclude them from indexing:

     $zendSearch->addDocument('doc1', ['title' => 'Test', 'exclude' => 'field']);
     

Debugging

• Verify Index List documents to debug:

  $docs = $zendSearch->getDocuments();
  

• Check Errors Enable PHP error logging and inspect ZendSearchException:

  try {
      $zendSearch->search('invalid_query');
  } catch (\Exception $e) {
      Log::error($e->getMessage());
  }
  

Extension Points

1. Custom Scoring Override the default ranking logic by extending the class:

   class CustomZendSearch extends \Diszo2009\ZendSearch\ZendSearch {
       public function search($query, $options = []) {
           $results = parent::search($query, $options);
           // Custom scoring logic here
           return $results;
       }
   }
   

2. Plugin System Add pre/post hooks for indexing/searching:

   $zendSearch->on('beforeSearch', function ($query) {
       // Modify query or log
   });
   

3. Async Indexing Use Laravel Queues to offload indexing:

   Post::find($id)->dispatch(new IndexPostJob($id));
   

   // In IndexPostJob
   public function handle() {
       $post = Post::find($this->postId);
       app('zendsearch')->addDocument("post_{$post->id}", [...]);
       app('zendsearch')->commit();
   }
   

4. Multi-Index Support Maintain separate indexes for different data types:

   $blogIndex = new ZendSearch(storage_path('app/blog_index'));
   $productIndex = new ZendSearch(storage_path('app/product_index'));