README.md

Filament Scout Plugin

Plugin to integrate Laravel Scout into Filament Global Search and Table Search. Plus a ScoutSelect component which enhances the standard Select Field with scout search capabilities.

Pre-Requesites

• Laravel Scout: Install and configure Laravel Scout as described in the Laravel Docs.

Installation

You can install the package via composer:

composer require kainiklas/filament-scout

Table Search

To use Scout Search instead of the default search on a table, add the trait InteractsWithScout to any Page which contains a table, e.g. app\Filament\Resources\MyResource\Pages\ListMyResources.php:

use Kainiklas\FilamentScout\Traits\InteractsWithScout;

class ListMyResources extends ListRecords
{
    use InteractsWithScout;
}

The table defined in the resource needs to be searchable() as described in the Filament table docs. Making each column searchable is not required anymore, as the content of what is searchable is defined within scout.

Increase the number of search results

Depending on the scout engine you may have limitations on how many search results you get back. This can be adjusted in two places:

1. Search Limit

Add the following env variable to adjust the limit of search results:

SCOUT_SEARCH_LIMIT=100

100 is the default value within this pagacke. For example meilisearch has a default limit of 20.

2. Index Settings (Example for meilisearch)

Within meilisearch there is a default limit of 1000 total hits which is also the upper bound for the search limit. That means if you want to have more than 1000 search results, you need to adapt both: the search limit and the index settings. The index settings can be adjusted within config\scout.php:

'index-settings' => [
  MyClass::class => [
    'pagination' => [
      'maxTotalHits' => 10000
    ],
  ],
],

Then run the following command to sync the settings: php artisan scout:sync-index-settings

Global Search

1. Check how to enable Global Search in the Filament Documentation.
   • Set a $recordTitleAttribute on your resource: Setting global search result title.
   • (Optional) Add details by implementing the method getGlobalSearchResultDetails(Model $record) in your Resource: Adding extra details to global search results.

class ContractResource extends Resource
{
    // required to enable global search
    protected static ?string $recordTitleAttribute = 'name';

    // optional: details
    public static function getGlobalSearchResultDetails(Model $record): array
    {
        return [
            'Category' => $record->category->name,
        ];
    }
}

2. Add the Plugin FilamentScoutPlugin to your panel configuration, e.g., in app\Providers\Filament\AdminPanelProvider.php.

use Kainiklas\FilamentScout\FilamentScoutPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            $plugins([
                FilamentScoutPlugin::make()
            ]);
    }
}

Meilisearch

If you are using Meilisearch, you can activate meilisearch specific features (search context highlighting):

1. Configure the plugin.

use Kainiklas\FilamentScout\FilamentScoutPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            $plugins([
                FilamentScoutPlugin::make()
                    ->useMeilisearch() // enables meilisearch specific features
            ]);
    }
}

2. (Optional) Implement/ Adapt getGlobalSearchResultDetails() in your Resource:

public static function getGlobalSearchResultDetails(Model $record): array
    {
        // change the filament default implementation from this
        // return [
        //     'AttributeTitle' => $record->attribute_name
        // ];
        
        // to this
        return [
            'scout_attribute_name' => "AttributeTitle"
        ];
    }

Select Form Field

To enable scout search in your select form fields use the provided ScoutSelect component:

use Kainiklas\FilamentScout\Forms\Components\ScoutSelect;
 
ScoutSelect::make('company_id')
    ->searchable()
    ->relationship('company', 'name')
    ->useScout() // must be called after relationship()

Technically, the ScoutSelect component inherits from Filament\Forms\Components\Select. The useScout() method sets a new getSearchResultsUsing() closure which uses scout.

Important: The useScout() method needs to be called after the relationship method. Otherwise it is overriden by the relationship() method.

Hint: Only values which are accessible and defined by scout are searchable.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Kai Niklas

License

The MIT License (MIT). Please see License File for more information.