Search Redis Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/search-redis
   

   Ensure redis-stack-server is installed and configured (see REDIS.md).

2. Configure Redis Stack: Edit /opt/redis-stack/etc/redis-stack.conf:

   port 6579
   daemonize no
   requirepass your_secure_password
   

   Restart Redis Stack:

   sudo systemctl restart redis-stack-server
   

3. Environment Setup: Add to .env:

   REDIS_SEARCH_HOST=localhost
   REDIS_SEARCH_PORT=6579
   REDIS_SEARCH_PASSWORD=your_secure_password
   REDIS_SEARCH_TABLE=1  # Optional: Defaults to 0
   

4. First Use Case: Index a model (e.g., Product) via Artisan:

   php artisan baks:search:redis:index Product
   

   Verify with Redis CLI:

   redis-cli -p 6579
   127.0.0.1:6579> AUTH your_secure_password
   127.0.0.1:6579> FT.SEARCH products * RETURN 2
   

Implementation Patterns

Core Workflows

1. Indexing Models:

   • Use the baks:search:redis:index Artisan command to index Eloquent models:

     php artisan baks:search:redis:index Product --fields=name,description,price
     

   • Dynamic Fields: Pass --fields to specify searchable fields (default: all non-relationship fields).
   • Batch Indexing: For large datasets, use --chunk=1000 to process in batches.

2. Searching:

   • Basic Search:

     use BaksDev\SearchRedis\Facades\SearchRedis;
     
     $results = SearchRedis::search('Product', 'laptop')->get();
     

   • Advanced Queries:

     $results = SearchRedis::search('Product')
         ->text('laptop')
         ->filter('price', ['>', 500])
         ->sortBy('price', 'desc')
         ->limit(10)
         ->get();
     

   • Pagination:

     $results = SearchRedis::search('Product')->paginate(10);
     

3. Schema Management:

   • Create/Update Index:

     php artisan baks:search:redis:schema Product
     

   • Drop Index:

     php artisan baks:search:redis:drop Product
     

4. Real-Time Updates:

   • Observers: Attach to model events for auto-indexing:

     use BaksDev\SearchRedis\Observers\SearchRedisObserver;
     
     Product::observe(SearchRedisObserver::class);
     

   • Manual Sync:

     $product = Product::find(1);
     SearchRedis::sync($product); // Updates index on save
     

5. Integration with Laravel Scout:

   • Override searchableAs in your model:

     public function searchableAs()
     {
         return 'products'; // Custom index name
     }
     

   • Use SearchRedisEngine:

     use BaksDev\SearchRedis\Scout\SearchRedisEngine;
     
     class Product extends Model
     {
         public function toSearchableArray()
         {
             return ['name', 'description'];
         }
     
         public function shouldBeSearchable()
         {
             return true;
         }
     }
     

Gotchas and Tips

Pitfalls

1. Redis Stack Compatibility:

   • Ensure Redis Stack (not vanilla Redis) is installed. The package relies on RedisSearch module.
   • Error: FT.SEARCH not found → Redis Stack not running or misconfigured.
   • Fix: Verify with redis-cli -p 6579 FT._LIST (should return 1) "products" or similar).

2. Field Mapping:

   • Issue: Text fields not searchable → Missing TEXT tag in schema.
   • Fix: Explicitly define schema via Artisan:

     php artisan baks:search:redis:schema Product --fields="name:TEXT,description:TEXT,price:NUMERIC"
     

3. Password Authentication:

   • Gotcha: Forgotten REDIS_SEARCH_PASSWORD in .env → Silent failures.
   • Debug: Test connection manually:

     redis-cli -p 6579 AUTH your_password
     

4. Index Naming Collisions:

   • Problem: Multiple models using default index name (model_name).
   • Solution: Customize index names in .env or via searchableAs().

5. Large Datasets:

   • Performance: Indexing 100K+ records may time out.
   • Workaround: Use --chunk=500 and run in queue jobs:

     SearchRedis::index(Product::query(), 500);
     

Debugging Tips

1. Schema Inspection:

   redis-cli -p 6579 FT._INFO products
   

   • Check SCHEMA field for field definitions.

2. Query Logging: Enable debug mode in .env:

   REDIS_SEARCH_DEBUG=true
   

   • Logs raw RedisSearch queries to storage/logs/redis-search.log.

3. Common Errors:

   • IndexNotFound: Run php artisan baks:search:redis:schema ModelName.
   • FieldNotFound: Verify field names match the schema (case-sensitive).

Extension Points

1. Custom Scoring: Override SearchRedis facade to add custom scoring:

   SearchRedis::search('Product')->addScoring('popularity', 0.5);
   

2. Pre/Post-Index Hooks: Extend the SearchRedisObserver:

   namespace App\Observers;
   
   use BaksDev\SearchRedis\Observers\SearchRedisObserver;
   use App\Models\Product;
   
   class CustomSearchObserver extends SearchRedisObserver
   {
       public function saving(Product $model)
       {
           // Pre-index logic
       }
   
       public function saved(Product $model)
       {
           // Post-index logic
       }
   }
   

3. Multi-Tenant Indexing: Dynamically set index names based on tenant:

   SearchRedis::setIndexName('products_' . auth()->id());
   

4. Async Indexing: Use Laravel Queues to defer indexing:

   SearchRedis::queueSync($model); // Dispatches a job
   

   • Implement ShouldQueue in the observer.

5. Hybrid Search: Combine with Laravel Scout for fallback:

   if (!SearchRedis::isAvailable()) {
       return $model->search($query);
   }