Scout Advanced Meilisearch Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require omure/scout-advanced-meilisearch
   

2. Configure Scout Update config/scout.php:

   'driver' => env('SCOUT_DRIVER', 'meilisearch_advanced'),
   'meilisearch_advanced' => [
       'host' => env('MEILISEARCH_HOST', 'http://127.0.0.1:7700'),
       'index_name' => env('MEILISEARCH_INDEX', 'laravel'),
       'api_key' => env('MEILISEARCH_MASTER_KEY', null),
   ],
   

3. First Use Case Define a searchable model:

   use Omure\ScoutAdvancedMeilisearch\Searchable;
   
   class Product extends Model
   {
       use Searchable;
   
       public function toSearchableArray()
       {
           return [
               'name' => $this->name,
               'price' => $this->price,
               'tags' => $this->tags,
               'created_at' => $this->created_at,
           ];
       }
   }
   

   Run indexing:

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

Implementation Patterns

Querying with Extended Syntax

Basic Filtering

// Range queries
$products = Product::search('laptop')->where('price', '>=', 500)->get();

// Between ranges
$products = Product::search('phone')->whereBetween('price', [300, 800])->get();

// Complex conditions
$products = Product::search('electronics')
    ->where(function ($query) {
        $query->where('price', '<=', 1000)
              ->orWhere('tags', 'contains', 'sale');
    })
    ->get();

Array Field Searching

// Search within nested arrays
$products = Product::search('wireless')
    ->where('tags', 'contains', 'bluetooth')
    ->get();

// Exact array matching
$products = Product::search('accessories')
    ->where('tags', '=', ['usb', 'cable'])
    ->get();

Workflows

Dynamic Filtering

// Build filters from request
$filters = request()->query('filters', []);
$query = Product::search(request('q'));

foreach ($filters as $field => $value) {
    if (str_contains($value, ',')) {
        $query->whereIn($field, explode(',', $value));
    } else {
        $query->where($field, $value);
    }
}

Pagination with Filters

$results = Product::search('gadget')
    ->where('price', '<=', 300)
    ->paginate(10);

Hybrid Search

// Combine full-text and attribute filters
$results = Product::search('wireless headphones')
    ->where('brand', 'Sony')
    ->orderBy('price', 'asc')
    ->get();

Integration Tips

• Model Events: Use searchable:saved/searchable:deleted for custom logic.
• Scout Events: Listen to scout:searching for query logging/analytics.
• Meilisearch UI: Pair with Meilisearch Dashboard for index management.

Gotchas and Tips

Common Pitfalls

1. Index Schema Mismatch

   • Ensure toSearchableArray() returns fields matching your Meilisearch index schema.
   • Fix: Run php artisan scout:flush and re-import after schema changes.

2. Filterable Attributes

   • Forgetting to declare filterable attributes in Meilisearch UI breaks where() clauses.
   • Fix: Update index settings via API or dashboard:

     curl -X POST "http://localhost:7700/indexes/laravel/settings" \
          -H "Content-Type: application/json" \
          -d '{"filterableAttributes": ["price", "brand", "tags"]}'
     

3. Array Field Queries

   • contains only works on indexed array fields (not raw database arrays).
   • Fix: Ensure tags is indexed as an array in Meilisearch.

4. Total Count Accuracy

   • Avoid ->get() with large datasets; use ->count() or ->paginate() instead.

Debugging Tips

• Query Inspection

  $query = Product::search('test')->where('price', '>', 100);
  dd($query->toMeilisearchQuery()); // Raw Meilisearch query
  

• Index Health Check Meilisearch logs or use:

  curl http://localhost:7700/health
  

• Performance

  • Use ->limit(100) during development to avoid overloading Meilisearch.
  • Monitor index size with:

    curl http://localhost:7700/indexes/laravel/stats
    

Extension Points

1. Custom Drivers Extend Omure\ScoutAdvancedMeilisearch\Drivers\MeilisearchAdvancedDriver for protocol-specific logic.

2. Query Macros Add reusable query methods:

   Scout::extend(function ($scout) {
       $scout->macro('inStock', function ($query) {
           return $query->where('stock', '>', 0);
       });
   });
   

3. Collection Driver for Tests Use collection_advanced in phpunit.xml:

   <env name="SCOUT_DRIVER" value="collection_advanced"/>
   

Configuration Quirks

• Master Key: If omitted, Meilisearch uses no authentication (not recommended for production).
• Index Name: Must match the index created in Meilisearch (laravel by default).
• Async Indexing: For large datasets, consider chunking:

  Product::chunk(100, function ($products) {
      $products->searchable();
  });