Laravel Scout Tntsearch Driver Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require teamtnt/laravel-scout-tntsearch-driver
   

   Publish the config file:

   php artisan vendor:publish --provider="TeamTNT\ScoutTNTSearchDriver\ScoutTNTSearchDriverServiceProvider"
   

2. Configure config/scout.php:

   'driver' => 'tntsearch',
   

   Ensure config/scout-tntsearch.php is updated with your TNTSearch index path (default: storage/tntsearch).

3. First Use Case: Define a model using Scout:

   use Laravel\Scout\Searchable;
   
   class Post extends Model
   {
       use Searchable;
   
       public function toSearchableArray()
       {
           return [
               'title' => $this->title,
               'body' => $this->body,
           ];
       }
   }
   

   Index a model:

   $post = Post::find(1);
   $post->searchable();
   

Implementation Patterns

Core Workflows

1. Indexing:

   • Use searchable() on model instances to index them.
   • Bulk index with Post::all()->each->searchable().
   • Schedule indexing via Laravel Queues for large datasets:

     Post::chunk(100, function ($posts) {
         $posts->each->searchable();
     });
     

2. Searching:

   • Basic search:

     $results = Post::search('laravel')->get();
     

   • Advanced queries using TNTSearch syntax:

     $results = Post::search('title:"Laravel" AND body:scout')->get();
     

   • Paginate results:

     $results = Post::search('query')->paginate(10);
     

3. Customizing Search Behavior:

   • Override toSearchableArray() for model-specific fields.
   • Use scout:import artisan command for initial bulk indexing:

     php artisan scout:import "App\Models\Post"
     

Integration Tips

• Hybrid Search: Combine with other Scout drivers (e.g., Algolia) for fallback:

  'driver' => env('SCOUT_DRIVER', 'tntsearch'),
  

• Reindexing: Use scout:flush to clear the index before reindexing:

  php artisan scout:flush "App\Models\Post"
  php artisan scout:import "App\Models\Post"
  

• Custom TNTSearch Config: Extend config/scout-tntsearch.php for field mappings or analyzers:

  'fields' => [
      'title' => ['boost' => 2],
      'body' => ['analyzer' => 'snowball'],
  ],
  

Gotchas and Tips

Pitfalls

1. Index Path Permissions:

   • Ensure storage/tntsearch is writable by the web server:

     chmod -R 775 storage/tntsearch
     

   • Debug: Check storage/logs/laravel.log for permission errors.

2. Case Sensitivity:

   • TNTSearch is case-sensitive by default. Use analyzers (e.g., lowercase) for case-insensitive searches:

     'fields' => [
         'title' => ['analyzer' => 'lowercase'],
     ],
     

3. Large Datasets:

   • Avoid indexing millions of records at once. Use chunking or queues:

     Post::chunk(500, function ($posts) {
         $posts->each->searchable();
     })->onQueue('indexing');
     

4. Special Characters:

   • Escape special characters in queries (e.g., + or -) or use TNTSearch’s syntax:

     $results = Post::search('title:"Laravel + Scout"')->get();
     

Debugging

• Query Inspection:

  • Enable TNTSearch logging in config/scout-tntsearch.php:

    'debug' => true,
    

  • View raw queries in storage/logs/tntsearch.log.

• Index Validation:

  • Verify the index structure with:

    php artisan tntsearch:dump
    

  • Check for corrupted indices by reindexing a subset of data.

Extension Points

1. Custom Analyzers:

   • Extend TNTSearch’s analyzers by publishing and modifying config/tntsearch.php:

     'analyzers' => [
         'custom_analyzer' => [
             'tokenizer' => 'standard',
             'filter' => ['lowercase', 'stemmer'],
         ],
     ],
     

   • Reference: TNTSearch Analyzers.

2. Model Events:

   • Hook into searchable events for pre/post-processing:

     Post::searchable(function ($model) {
         $model->body = str_replace(['&', ';'], '', $model->body);
     });
     

3. Fuzzy Search:

   • Enable fuzzy matching in queries:

     $results = Post::search('laravel~')->get(); // ~ allows 1 typo