Laravel Searchable Laravel Package

Getting Started

Install the package via Composer:

composer require spatie/laravel-searchable

Begin by identifying models or external data sources you want searchable—common examples include User, BlogPost, or API-backed entities. For models, implement the Spatie\Searchable\Searchable interface and define a getSearchResult() method that returns a SearchResult object (with title, URL, and the model instance). Then, in your search logic (e.g., controller), instantiate new Search(), register models (and optionally specify attributes like name or title) via registerModel(), and call ->search('query').

Implementation Patterns

• Model-based search: Use registerModel(Model::class, 'field1', 'field2') for simple cases, or pass an array for multiple attributes. For advanced control, pass a closure to receive a ModelSearchAspect instance and chain scopes (->active()), eager loads (->with()), or exact/partial match definitions (->addExactSearchableAttribute(), ->addSearchableAttribute()).
• Custom search aspects: Extend SearchAspect and implement getResults(string $term): Collection to integrate non-model sources (e.g., external APIs, files, cached data). Register them via registerAspect(CustomAspect::class).
• Result grouping & templating: Use groupByType() on the SearchableCollection to separate results by source. Override the default type label by adding a public $searchableType property on your model or aspect class.
• Limiting results: Apply limitAspectResults(int $count) before search() to cap results per aspect—useful for performance or UI balance.

Gotchas and Tips

• Performance: Each registered aspect performs a separate database/API query—avoid over-registering or large, unscoped searches. Use scopes (e.g., ->active()) to narrow results early.
• Exact matches: When using addExactSearchableAttribute(), note that leading/trailing whitespace in database values will break matches (fixed in v1.13.1); consider ->whereRaw('TRIM(column) = ?', $term) if needed.
• Special characters: The package handles them safely (v1.10.0+), but ensure your DB collation supports case-insensitive matching (e.g., MySQL utf8mb4_unicode_ci).
• Debugging: Add dd($searchResults) early—inspect the SearchResult objects’ structure, and verify your getSearchResult() methods return valid title, url, and model properties.
• Extensibility: Override default behavior by extending core classes (e.g., SearchAspect, SearchableCollection) or tailoring Blade render logic. You can also add custom filters or scoring via aspect closures.