Laravel Scout Tntsearch Driver Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   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',
   

   Update config/scout-tntsearch.php with your TNTSearch index path (default: storage/tntsearch) and optionally enable stopwords:

   'tntsearch' => [
       'path' => storage_path('tntsearch'),
       'stopwords' => ['a', 'the', 'in', 'and'], // New in v16.1.0
   ],
   

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();
     });
     

   • Stopwords Note: Stopwords are applied automatically during indexing (e.g., scout:import, tntsearch:import, or model saves).

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 for initial bulk indexing:

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

   • Read-Replica Compatibility: Imports now work on read-only database connections (v16.1.0).

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, analyzers, or stopwords:

  'fields' => [
      'title' => ['boost' => 2],
      'body' => ['analyzer' => 'snowball'],
  ],
  'stopwords' => ['a', 'the', 'in'], // New in v16.1.0
  

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();
     

5. Stopwords Quirk:

   • Stopwords are applied at indexing time, so reimport models after updating config/scout-tntsearch.php:

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

6. TNTSearch Version Compatibility:

   • Requires teamtnt/tntsearch ^4.0|^5.0 (v16.1.0). Older versions may fail on boot due to missing fuzziness setters.

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
     

4. Laravel 11+ Compatibility:

   • Ensure the service provider is registered in bootstrap/providers.php:

     TeamTNT\ScoutTNTSearchDriver\ScoutTNTSearchDriverServiceProvider::class,
     

NO_UPDATE_NEEDED was not applicable—this assessment has been **fully updated** to reflect the new features (stopwords, read-replica support) and fixes (TNTSearch version requirement, Laravel 11+ registration).