Filament Scout Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require kainiklas/filament-scout
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Kainiklas\FilamentScout\FilamentScoutServiceProvider"
   

2. Configure Scout Driver Ensure your config/scout.php is properly set up (e.g., Algolia, Meilisearch, or database driver). Example for Algolia:

   'driver' => env('SCOUT_DRIVER', 'algolia'),
   'algolia' => [
       'id' => env('ALGOLIA_APP_ID'),
       'secret' => env('ALGOLIA_SECRET'),
       'index_prefix' => env('ALGOLIA_INDEX_PREFIX', ''),
   ],
   

3. Enable Plugin in Filament Register the plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Kainiklas\FilamentScout\Plugin::make(),
           ]);
   }
   

4. First Use Case: Global Search Ensure your model uses HasSearchable trait and has a toSearchableArray() method:

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

   Now, Filament’s global search will automatically leverage Scout for indexed models.

Implementation Patterns

Workflow: Integrating Scout with Filament Tables

1. Table Search Integration Use the ScoutSearch column type in Filament tables:

   use Kainiklas\FilamentScout\Columns\ScoutSearchColumn;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               ScoutSearchColumn::make('title'), // Searches the 'title' field in Scout
           ]);
   }
   

2. Customizing Search Fields Override toSearchableArray() for granular control:

   public function toSearchableArray()
   {
       return [
           'custom_field' => $this->title . ' ' . $this->slug,
       ];
   }
   

3. ScoutSelect Component Replace standard Select fields with ScoutSelect for autocomplete:

   use Kainiklas\FilamentScout\Forms\Components\ScoutSelect;
   
   public static function form(Form $form): Form
   {
       return $form
           ->components([
               ScoutSelect::make('author_id')
                   ->label('Author')
                   ->options(Author::class), // Model class for Scout indexing
           ]);
   }
   

4. Bulk Actions with Scout Combine Scout with Filament’s bulk actions:

   public static function table(Table $table): Table
   {
       return $table
           ->actions([
               Tables\Actions\DeleteAction::make(),
           ])
           ->bulkActions([
               Tables\Actions\BulkActionGroup::make([
                   Tables\Actions\DeleteBulkAction::make(),
               ]),
           ]);
   }
   

   Scout ensures fast filtering even with large datasets.

Integration Tips

• Hybrid Search: Combine Scout for global search and database queries for table-specific filters:

  $table->columns([
      ScoutSearchColumn::make('title'), // Scout-powered
      TextColumn::make('status'),      // Database query
  ]);
  

• Soft Deletes: Ensure Scout handles soft deletes by implementing shouldBeSearchable():

  public function shouldBeSearchable()
  {
      return !$this->deleted_at;
  }
  

• Real-Time Updates: Use Scout’s searchable event to sync changes:

  protected static function booted()
  {
      static::saved(function ($model) {
          $model->searchable();
      });
  }
  

Gotchas and Tips

Pitfalls

1. Indexing Delays Scout may not reflect real-time changes immediately. Use searchable() manually or set up a queue job:

   Post::find($id)->searchable(); // Force reindex
   

   Or queue it:

   Post::find($id)->searchable()->afterCommit();
   

2. Case Sensitivity Scout’s default search is case-insensitive, but some drivers (e.g., Meilisearch) may vary. Configure in config/scout.php:

   'meilisearch' => [
       'searchable_attributes' => ['title', 'body'],
       'sortable_attributes' => ['title'],
       'filterable_attributes' => [],
   ],
   

3. Pagination Conflicts Scout’s cursor() pagination may clash with Filament’s default. Override in your resource:

   public static function getPages(): array
   {
       return [
           'index' => Pages\ListPosts::route('/'),
       ];
   }
   

Debugging

• Check Indexed Data: Use Scout’s Tinker commands:

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

• Log Search Queries: Enable Scout logging in config/scout.php:

  'log' => env('SCOUT_LOG', false),
  

• Clear Cache: If issues persist, clear Filament and Scout caches:

  php artisan filament:cache-clear
  php artisan scout:flush
  

Extension Points

1. Custom Search Logic Extend ScoutSearchColumn for custom behavior:

   use Kainiklas\FilamentScout\Columns\ScoutSearchColumn;
   
   class CustomScoutSearchColumn extends ScoutSearchColumn
   {
       protected function getSearchableFields(): array
       {
           return ['title', 'custom_meta'];
       }
   }
   

2. Driver-Specific Config Override Scout’s driver config per model:

   class Post extends Model
   {
       use Searchable;
   
       public function searchableAs()
       {
           return 'posts_custom_index';
       }
   }
   

3. Fallback to Database Implement a fallback for unindexed models in ScoutSearchColumn:

   protected function getFallbackQuery(): Builder
   {
       return $this->getModel()::query()
           ->where('title', 'like', '%' . $this->getQuery() . '%');
   }
   

4. Performance Tuning Limit Scout results in Filament tables:

   ScoutSearchColumn::make('title')
       ->limit(100) // Reduce memory usage
       ->debounce(500), // Adjust for UI responsiveness