Laravel Searchable

https://github.com/mozex/laravel-searchable
Admin
Laravel Searchable is a Laravel package that adds advanced multi-column database search to Eloquent...
Tokens:47,600
Snippets:311
Trust Score:8.5
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### configurePackage method for package setup

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-service-provider.md

Configures the package: sets the name to 'laravel-searchable', discovers the config file, and registers an install command that publishes the config and runs askToStar(). The install command leaves existing config files untouched and skips the star prompt under --no-interaction.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-searchable')
        ->hasConfigFile()
        ->hasInstallCommand(function (InstallCommand $command): void {
            $command
                ->publishConfigFile()
                ->endWith(fn (InstallCommand $command) => $this->askToStar($command));
        });
}
```

--------------------------------

### Install laravel-searchable with Composer

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Install the package via Composer. Requires PHP 8.2+.

```bash
composer require mozex/laravel-searchable
```

--------------------------------

### Usage examples for apply()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Two examples of calling apply() directly. The first shows basic usage with search and sort column from the Livewire component. The second shows per-table overrides for the 'in' columns and maxTerms.

```php
use Mozex\Searchable\Filament\RelevanceSort;

// Wiring it yourself inside a modifyQueryUsing / custom sort, reusing the
// same decision logic ($search and $sortColumn come from your table's
// livewire component):
RelevanceSort::apply($query, $search, $sortColumn);

// With per-table overrides
RelevanceSort::apply($query, $search, $sortColumn, in: ['title', 'body'], maxTerms: 5);
```

--------------------------------

### Usage examples for the search scope

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Examples covering basic search, composing with existing constraints, multi-word searches with phrases, and empty/whitespace-only searches that return all results.

```php
// Basic: search all configured columns, order by relevance
$results = Comment::search('laravel')->get();

// Compose with existing constraints — search is ANDed with them
Comment::query()
    ->where('published', true)
    ->search($request->input('q'))
    ->paginate();

// Multi-word: every word must match somewhere; phrases stay together
Author::search('Doe Jane')->get();            // matches "Jane Doe"
Author::search('"Jane Doe" senior')->get();   // quoted phrase + loose term

// Empty / whitespace-only search acts as no search at all
Comment::search('   ')->get(); // returns everything, like Comment::query()->get()
```

--------------------------------

### Publish configuration with searchable:install

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Publishes the config/searchable.php configuration file. No migrations are required.

```bash
php artisan searchable:install
```

--------------------------------

### applySearch()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Documentation for the applySearch() method, including its signature, parameters, return type, errors, and usage examples.

```APIDOC
## `applySearch()`

### Description
Invokes the search scope directly on a given builder, bypassing the `search` name. Use it when the model's `Builder` already owns a `search()` method (e.g., Corcel's `PostBuilder`) or when a parent class already declares `scopeSearch` with an incompatible signature.

### Method
`applySearch` (public method)

### Signature
```php
public function applySearch(
    Builder $query,
    ?string $search,
    string|array $in = [],
    string|array $include = [],
    string|array $except = [],
    ?int $externalLimit = null,
    bool $orderByRelevance = true,
    ?int $maxTerms = null
): void
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$query` | `Builder<static>` | yes | — | The query to apply the scope to. |
| `$search` | `?string` | yes | — | Same semantics as the scope's `$search`. |
| `$in` | `string\|array<int, string>` | no | `[]` | Column override (see scope). |
| `$include` | `string\|array<int, string>` | no | `[]` | Column addition (see scope). |
| `$except` | `string\|array<int, string>` | no | `[]` | Column removal (see scope). |
| `$externalLimit` | `?int` | no | `null` | Cross-database key cap override. |
| `$orderByRelevance` | `bool` | no | `true` | `false` to omit the relevance `ORDER BY`. |
| `$maxTerms` | `?int` | no | `null` | Term-split cap override. |

### Return type
`void` — the modifier applies to the passed `$query` object; execute it afterwards (`->get()`, `->paginate()`, etc.).

### Errors
None thrown by the method itself. It simply delegates to `scopeSearch()`. If the term/column resolution yields nothing, it is a no-op (see scope behavior).

### Examples

```php
// Basic usage — apply on a fresh query, then execute
$query = Product::query();
$query->getModel()->applySearch($query, 'term');
$results = $query->get();

// Error-handling / conflict case: the Builder owns search(), so call applySearch directly
$query = Product::query();
$query->getModel()->applySearch($query, 'term', in: ['title', 'body'], except: ['author.name']);
$results = $query->get();

// Delegate a custom Builder's search() back to applySearch so callers keep using $query->search()
class ProductBuilder extends \Corcel\Model\Builder\PostBuilder
{
    public function search($term = false, ...$args): self
    {
        $query = Product::query();
        (new Product)->applySearch($query, $term, ...$args);
        return $query;
    }
}
```
```

--------------------------------

### Panel registration with globalSearch()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/global-search-provider.md

Shows how to register the SearchableGlobalSearchProvider on a Filament panel using the globalSearch() method. Includes the import statement and a panel configuration example.

```php
use Mozex\Searchable\Filament\SearchableGlobalSearchProvider;

// Panel registration (App\Providers\Filament\AdminPanelProvider.php)
return $panel
    ->id('admin')
    ->path('admin')
    ->globalSearch(SearchableGlobalSearchProvider::class);
```

--------------------------------

### advancedSearchable() usage examples

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-service-provider.md

Shows three usage examples of the advancedSearchable macro: basic usage on one column, advanced configuration with except, externalLimit, and maxTerms, and custom scope name with method: 'databaseSearch'.

```php
use Filament\Tables\Columns\TextColumn;

// Basic — add to ONE column in the table; searches all the model's
// searchableColumns() (and the automatic RelevanceSort scope ranks results)
TextColumn::make('title')
    ->advancedSearchable()
    ->sortable(),

// Advanced configuration
TextColumn::make('title')
    ->advancedSearchable(except: ['author.name'], externalLimit: 200, maxTerms: 5),

// Custom scope name (e.g., when coexisting with Laravel Scout)
TextColumn::make('name')->advancedSearchable(method: 'databaseSearch'),
```

--------------------------------

### Usage examples for applyRelevanceSort

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Shows two usage patterns: typical use via RelevanceSort for Filament tables, and direct use when your own code already built the WHERE clause. The direct example calls applyRelevanceSort on the model with a search string, column override, and maxTerms limit.

```php
use Filament\Tables\Table;
use Mozex\Searchable\Filament\RelevanceSort;

// Typical usage — called by RelevanceSort for Filament tables (see relevance-sort.md)
RelevanceSort::apply($query, $search, $sortColumn);

// Direct use when your own code already built the WHERE
$query = Post::query()->where('published', true);
$query->getModel()->applyRelevanceSort(
    $query,
    'laravel',
    in: ['title', 'body'],
    maxTerms: 5,
);
```

--------------------------------

### applySearch() usage examples

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Three usage examples for applySearch(): basic application on a fresh query, a conflict case where the Builder owns search() so applySearch is called directly with column overrides, and a custom Builder that delegates its search() method back to applySearch so callers keep using $query->search(). The method returns void, so the query must be executed afterwards.

```php
// Basic usage — apply on a fresh query, then execute
$query = Product::query();
$query->getModel()->applySearch($query, 'term');
$results = $query->get();

// Error-handling / conflict case: the Builder owns search(), so call applySearch directly
$query = Product::query();
$query->getModel()->applySearch($query, 'term', in: ['title', 'body'], except: ['author.name']);
$results = $query->get();

// Delegate a custom Builder's search() back to applySearch so callers keep using $query->search()
class ProductBuilder extends \Corcel\Model\Builder\PostBuilder
{
    public function search($term = false, ...$args): self
    {
        $query = Product::query();
        (new Product)->applySearch($query, $term, ...$args);
        return $query;
    }
}
```

--------------------------------

### Example model with searchableColumns()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Example model using the Searchable trait and overriding `searchableColumns()` with various column descriptor formats: direct columns, dot-notation relations, and typed morph relations. The `commentable:post.title` syntax is required for MorphTo relations; plain dot notation like `commentable.title` is skipped.

```php
use Mozex\Searchable\Searchable;
use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    use Searchable;

    public function searchableColumns(): array
    {
        return [
            'body',                       // direct column
            'author.name',                // BelongsTo
            'tags.name',                  // HasMany / BelongsToMany
            'commentable:post.title',     // morph target type: post
            'commentable:post.author.name', // nested inside the morph target
        ];
    }
}
```

--------------------------------

### .env - override searchable configuration via environment variables

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/configuration.md

Example .env settings to override the package defaults: sets max_terms to 5, external_limit to 200, and disables automatic Filament relevance ranking.

```bash
# .env — term cap of 5, larger external key cap, no automatic Filament ranking
SEARCHABLE_MAX_TERMS=5
SEARCHABLE_EXTERNAL_LIMIT=200
SEARCHABLE_FILAMENT_RELEVANCE_SORT=false
```

--------------------------------

### config/searchable.php - package configuration file

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/configuration.md

The full source of config/searchable.php, published by the searchable:install artisan command. Defines max_terms (default 10), external_limit (default 50), and filament.relevance_sort (default true), each read from environment variables with fallback defaults.

```php
return [
    'max_terms' => (int) env('SEARCHABLE_MAX_TERMS', 10),

    'external_limit' => (int) env('SEARCHABLE_EXTERNAL_LIMIT', 50),

    'filament' => [
        'relevance_sort' => (bool) env('SEARCHABLE_FILAMENT_RELEVANCE_SORT', true),
    ],
];
```

--------------------------------

### Resource attribute control for global search

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/global-search-provider.md

Shows how to define getGloballySearchableAttributes() on resources to control which attributes are searchable. Includes two examples: one using all searchable columns from the model, and one using a subset.

```php
class CourseResource extends Resource
{
    // Everything the model declared as searchable
    public static function getGloballySearchableAttributes(): array
    {
        return (new Course)->searchableColumns();
    }
}

class PostResource extends Resource
{
    // Or a subset — Post may declare more columns in searchableColumns()
    public static function getGloballySearchableAttributes(): array
    {
        return ['title', 'author.name'];
    }
}
```

--------------------------------

### Delegate Builder search() to applySearch() for Corcel PostBuilder

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Overrides the custom Builder's search() method to delegate back to applySearch(), so the rest of the codebase can keep calling $query->search() even when the Builder owns a search() method. The example extends Corcel's PostBuilder and returns a new query built from Product::query().

```php
class ProductBuilder extends \Corcel\Model\Builder\PostBuilder
{
    public function search($term = false, ...$args): self
    {
        $query = Product::query();
        (new Product)->applySearch($query, $term, ...$args);
        return $query;
    }
}
```

--------------------------------

### getResults(string $query): ?GlobalSearchResults

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/global-search-provider.md

Documentation for the getResults() method of the SearchableGlobalSearchProvider class, including parameters, return type, behavior, and usage examples.

```APIDOC
## getResults(string $query): ?GlobalSearchResults

### Description
Runs a global search across all panel resources, routing queries for Searchable models through the package's applySearch() and applying relevance ordering automatically. Returns a GlobalSearchResults object with categories keyed by each resource's plural model label, omitting resources with zero matching results.

### Method
N/A (PHP method)

### Endpoint
N/A (PHP method)

### Parameters
- **$query** (string) - Required - The raw global-search string from Filament.

### Return Type
`?GlobalSearchResults` (Filament\GlobalSearch\GlobalSearchResults) - A results object whose categories are keyed by each resource's getPluralModelLabel(); resources with zero matching results are omitted. Never null in this implementation.

### Behavior
1. All panel resources are fetched via Filament::getResources() and sorted by each resource's getGlobalSearchSort() (stable <=> on the nullable ints).
2. Resources failing canGloballySearch() are skipped.
3. Per resource: if its model uses the Searchable trait (via class_uses_recursive), search runs through getSearchableResults() (package path); otherwise it falls back to Filament's native $resource::getGlobalSearchResults($query).
4. Categories with no results are dropped.

### Example
```php
use Mozex\Searchable\Filament\SearchableGlobalSearchProvider;

// Panel registration (App\Providers\Filament\AdminPanelProvider.php)
return $panel
    ->id('admin')
    ->path('admin')
    ->globalSearch(SearchableGlobalSearchProvider::class);
```

Per-resource attribute control (each resource you want in global search must define getGloballySearchableAttributes(); resources without it — and models without the trait — are excluded/fall through):

```php
class CourseResource extends Resource
{
    // Everything the model declared as searchable
    public static function getGloballySearchableAttributes(): array
    {
        return (new Course)->searchableColumns();
    }
}

class PostResource extends Resource
{
    // Or a subset — Post may declare more columns in searchableColumns()
    public static function getGloballySearchableAttributes(): array
    {
        return ['title', 'author.name'];
    }
}
```
```

--------------------------------

### Search with ->search() scope

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Use the search() scope on the model or query builder. The shortest form calls Comment::search('term')->get(); chain with other constraints using query()->where(...)->search(...)->paginate().

```php
// Shortest form
Comment::search('term')->get();

// Chain with other constraints
Comment::query()->where('published', true)->search('term')->paginate();
```

--------------------------------

### Multi-word search with Author::search

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Shows multi-word search behavior: each word becomes an OR group across searchable columns, and groups are joined with AND. The first example finds an author named "Jane Doe" regardless of word order; the second matches "Jane" in the name and "acme.com" in the email.

```php
// Finds the author named "Jane Doe"
Author::search('Doe Jane')->get();

// "Jane" matches the name, "acme.com" matches the email
Author::search('Jane jane@acme.com')->get();
```

--------------------------------

### getSearchableResults method

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/global-search-provider.md

Builds search results for a Filament resource. Starts from the resource's global search query, applies the search with the globally searchable attributes (empty list falls back to searchableColumns), allows modification via modifyGlobalSearchQuery, and returns a collection of GlobalSearchResult objects.

```php
protected function getSearchableResults(string $resource, string $search): Collection
{
    /** @var Builder<Model> $query */
    $query = $resource::getGlobalSearchEloquentQuery();

    // Pass the resource's globally searchable attributes as the `in:` filter.
    // ...
    $query->getModel()->applySearch(
        $query,
        $search,
        in: $resource::getGloballySearchableAttributes(),
    );

    $resource::modifyGlobalSearchQuery($query, $search);

    return $this->buildResults($resource, $query);
}
```

--------------------------------

### applySearch() method signature

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Method signature for applySearch(), which invokes the search scope directly on a given builder, bypassing the 'search' name. Use it when the model's Builder already owns a search() method (e.g., Corcel's PostBuilder) or when a parent class declares scopeSearch with an incompatible signature. Returns void; the modifier applies to the passed $query object, so execute it afterwards with ->get(), ->paginate(), etc.

```php
public function applySearch(
    Builder $query,
    ?string $search,
    string|array $in = [],
    string|array $include = [],
    string|array $except = [],
    ?int $externalLimit = null,
    bool $orderByRelevance = true,
    ?int $maxTerms = null
): void
```

--------------------------------

### Register global Filament table relevance scope

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Registers a global Filament table configuration hook that attaches the scope() method as a query modifier to every table, enabling zero per-table setup for relevance ranking.

```php
public static function register(): void
{
    Table::configureUsing(function (Table $table): void {
        $table->modifyQueryUsing(self::scope(...));
    });
}
```

--------------------------------

### packageBooted() method

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-service-provider.md

Called after the package is booted. Delegates to the two registration hooks: registerFilamentMacros() and registerFilamentRelevanceSort().

```php
public function packageBooted(): void
{
    $this->registerFilamentMacros();
    $this->registerFilamentRelevanceSort();
}
```

--------------------------------

### Runtime and per-call overrides for searchable configuration

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/configuration.md

Shows runtime configuration override using config()->set() and a per-call override using named arguments (maxTerms, externalLimit) that takes precedence over config values.

```php
// Runtime override (e.g. in a service provider)
config()->set('searchable.max_terms', 3);

// Per-call override still wins over both of the above
Post::search('term', maxTerms: 25, externalLimit: 200)->get();
```

--------------------------------

### Apply relevance sort manually

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Apply relevance sorting manually, for example inside a modifyQueryUsing or a custom sort, reusing the same decision logic.

```php
// $search and $sortColumn come from your table's livewire component
RelevanceSort::apply($query, $search, $sortColumn);
```

--------------------------------

### Disable automatic relevance sort in code

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Disable automatic relevance sorting in code, for example in a service provider, when you prefer to wire ranking manually.

```php
use Mozex\Searchable\Filament\RelevanceSort;

RelevanceSort::$enabled = false;
```

--------------------------------

### Configure searchable.php defaults

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Default configuration for the package. `max_terms` controls how many words a multi-word search is split into; set to 1 to match every search as one literal phrase. `external_limit` sets how many matching keys a cross-database column fetches per term. `filament.relevance_sort` set to false disables ranked table search for every table. A `maxTerms` or `externalLimit` argument on a single call overrides these defaults.

```php
return [
    'max_terms' => (int) env('SEARCHABLE_MAX_TERMS', 10),

    'external_limit' => (int) env('SEARCHABLE_EXTERNAL_LIMIT', 50),

    'filament' => [
        'relevance_sort' => (bool) env('SEARCHABLE_FILAMENT_RELEVANCE_SORT', true),
    ],
];
```

--------------------------------

### Deep relation paths in searchableColumns()

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Define deep relation paths. Two-hop and deeper paths get a matched-or-not relevance score rather than exact/prefix/substring grading.

```php
public function searchableColumns(): array
{
    return [
        'title',
        'author.company.name',           // Post -> Author -> Company
        'comments.author.team.name',     // three hops, still fine
    ];
}
```

--------------------------------

### Package source tree layout

Source: https://github.com/mozex/laravel-searchable/blob/main/CLAUDE.md

Shows the src/ directory layout of the package, including the Searchable trait, service provider, Filament integration classes, and the config file. Useful for navigating the repository structure.

```text
src/
  Searchable.php                        # The trait (core feature)
  SearchableServiceProvider.php         # Registers config, the install command, and Filament macros conditionally
  Filament/
    SearchableGlobalSearchProvider.php  # Filament global search provider
    RelevanceSort.php                   # global hook: auto-ranks tables while searching
config/searchable.php                   # max_terms, external_limit, filament.relevance_sort
```

--------------------------------

### Manual re-registration of RelevanceSort::register()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Shows normal usage (no call needed) and manual re-registration in a custom provider if the automatic boot hook was disabled.

```php
// Normal usage: nothing to call — the service provider registers this at boot.

// Manual re-registration in a custom provider (only if you disabled the automatic boot hook):
RelevanceSort::register();
```

--------------------------------

### SearchableServiceProvider API

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-service-provider.md

Documentation for the SearchableServiceProvider class, including its boot hooks and the advancedSearchable TextColumn macro.

```APIDOC
## `packageBooted(): void`

### Description
Called after the package is booted. Delegates to the two registration hooks below.

### Method
`packageBooted`

### Signature
```php
public function packageBooted(): void
```

### Parameters
None.

### Return Type
`void`

### Errors
No exceptions are thrown by this method.

### Example
```php
$provider->packageBooted();
```
```

```APIDOC
## `registerFilamentRelevanceSort(): void`

### Description
Registers the global relevance sort (see RelevanceSort) only when Filament's `Table` class exists.

### Method
`registerFilamentRelevanceSort`

### Signature
```php
protected function registerFilamentRelevanceSort(): void
```

### Parameters
None.

### Return Type
`void`

### Errors
No exceptions are thrown by this method.

### Example
```php
$provider->registerFilamentRelevanceSort();
```
```

```APIDOC
## `registerFilamentMacros(): void`

### Description
Guards on `class_exists(TextColumn::class)`, then registers the `advancedSearchable` macro on `Filament\Tables\Columns\TextColumn`. The macro builds the search `WHERE` only because Filament runs the callback inside a nested `WHERE` where any `orderBy` would be discarded; ranking is applied separately by the global `RelevanceSort` scope.

### Method
`registerFilamentMacros`

### Signature
```php
protected function registerFilamentMacros(): void
```

### Parameters
None.

### Return Type
`void`

### Errors
No exceptions are thrown by this method.

### Example
```php
$provider->registerFilamentMacros();
```
```

```APIDOC
## `advancedSearchable()` TextColumn macro

### Description
Registers the `advancedSearchable` macro on `Filament\Tables\Columns\TextColumn`. This macro enhances a Filament table column with advanced search capabilities, allowing configuration of search columns, exclusions, external limits, and custom search methods. It is available whenever Filament is installed and the package has booted.

### Method
`advancedSearchable`

### Signature
```php
TextColumn::macro('advancedSearchable', function (
    array|string $in = [],
    array|string $include = [],
    array|string $except = [],
    ?int $externalLimit = null,
    string $method = 'search',
    ?int $maxTerms = null
) { ... })
```

### Parameters
- **$in** (array|string) - Optional - Default: `[]` - Column override passed to the model's search scope as the `in:` filter.
- **$include** (array|string) - Optional - Default: `[]` - Column addition passed to the scope.
- **$except** (array|string) - Optional - Default: `[]` - Column removal passed to the scope.
- **$externalLimit** (?int) - Optional - Default: `null` (→ `searchable.external_limit`, 50) - Cross-database key cap. Resolved eagerly because `$method` may name a user method that types the parameter as `int`.
- **$method** (string) - Optional - Default: `'search'` - The query-scope method name to invoke on the model's builder. Use this when the trait's scope was aliased (e.g., `scopeDatabaseSearch`) or for a custom search method.
- **$maxTerms** (?int) - Optional - Default: `null` (→ `searchable.max_terms`, 10) - Term-split cap, likewise resolved eagerly.

### Return Type
`$this` (the `TextColumn`), for chaining (e.g., `->advancedSearchable()->sortable()`).

### Errors
No exceptions are thrown by the macro itself. Invoking `$method` with a name that does not resolve to a scope/method on the builder propagates Laravel's `BadMethodCallException`.

### Examples
```php
use Filament\Tables\Columns\TextColumn;

// Basic — add to ONE column in the table; searches all the model's
// searchableColumns() (and the automatic RelevanceSort scope ranks results)
TextColumn::make('title')
    ->advancedSearchable()
    ->sortable(),

// Advanced configuration
TextColumn::make('title')
    ->advancedSearchable(except: ['author.name'], externalLimit: 200, maxTerms: 5),

// Custom scope name (e.g., when coexisting with Laravel Scout)
TextColumn::make('name')->advancedSearchable(method: 'databaseSearch'),
```
```

--------------------------------

### RelevanceSort class declaration

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Declares the RelevanceSort class, a static helper that automatically ranks Filament tables over Searchable models by relevance during table searches. Registered globally when Filament is installed via SearchableServiceProvider::registerFilamentRelevanceSort().

```php
class RelevanceSort
```

--------------------------------

### Quoted phrase search with Author::search

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Demonstrates using double quotes to keep a phrase together as one term. The first example matches the exact phrase "Jane Doe"; the second combines a quoted phrase with a loose term.

```php
// Matches "Jane Doe", not "Doe, Jane"
Author::search('"Jane Doe"')->get();

// Quoted phrase plus a loose term
Author::search('"Jane Doe" senior')->get();
```

--------------------------------

### apply

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Static method that applies relevance ranking to a query, with guard conditions and configurable overrides.

```APIDOC
## `apply(Builder $query, ?string $search, ?string $sortColumn, ...): void`

### Description
Applies relevance ranking to a query based on the current search term and sort column. It contains the decision logic separated from `scope()` for testability, and adds relevance `ORDER BY` keys when conditions are met.

### Method
`apply` (static method)

### Signature
`public static function apply(Builder $query, ?string $search, ?string $sortColumn, string|array $in = [], string|array $include = [], string|array $except = [], ?int $externalLimit = null, ?int $maxTerms = null): void`

### Parameters
- **$query** (`Builder<Model>`) - Required - The query to rank.
- **$search** (`?string`) - Required - Current table search term. `null`/blank → no-op.
- **$sortColumn** (`?string`) - Required - User-selected sort column. Filled → no-op (user sort wins).
- **$in** (`string|array<int, string>`) - Optional (default: `[]`) - Column override for the ranking.
- **$include** (`string|array<int, string>`) - Optional (default: `[]`) - Column addition for the ranking.
- **$except** (`string|array<int, string>`) - Optional (default: `[]`) - Column removal for the ranking.
- **$externalLimit** (`?int`) - Optional (default: `null`) - Cross-database key cap override.
- **$maxTerms** (`?int`) - Optional (default: `null`) - Term-split cap override.

### Return Type
`void`

### Behavior (guard conditions in order)
1. `filled($sortColumn)` → return (explicit column sort wins).
2. `blank($search)` → return (not searching does nothing — the table's own `defaultSort` is untouched).
3. Model does not use the `Searchable` trait (`in_array(Searchable::class, class_uses_recursive($model), true)`) → return.
4. Otherwise delegate to `$model->applyRelevanceSort($query, $search, ...)` — relevance `ORDER BY` leads, and whatever sort the table already applied becomes the tiebreaker.

Because Filament applies search (`WHERE`) and sorting as separate phases, `apply()` adds only the ranking; the WHERE comes from Filament's own search pipeline or from an `advancedSearchable()` column.

### Examples
```php
use Mozex\Searchable\Filament\RelevanceSort;

// Wiring it yourself inside a modifyQueryUsing / custom sort, reusing the
// same decision logic ($search and $sortColumn come from your table's
// livewire component):
RelevanceSort::apply($query, $search, $sortColumn);

// With per-table overrides
RelevanceSort::apply($query, $search, $sortColumn, in: ['title', 'body'], maxTerms: 5);
```
```

--------------------------------

### Register global search provider on panel

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Register the SearchableGlobalSearchProvider on your Filament panel to enable relevance ordering for global search results.

```php
use Mozex\Searchable\Filament\SearchableGlobalSearchProvider;

return $panel
    ->id('admin')
    ->path('admin')
    ->globalSearch(SearchableGlobalSearchProvider::class);
```

--------------------------------

### apply() method signature

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Shows the signature of the apply() method, which is separated from scope() for testability. It accepts the query, search term, sort column, and optional overrides for columns, limits, and term caps.

```php
public static function apply(
    Builder $query,
    ?string $search,
    ?string $sortColumn,
    string|array $in = [],
    string|array $include = [],
    string|array $except = [],
    ?int $externalLimit = null,
    ?int $maxTerms = null
): void
```

--------------------------------

### Composer test commands for laravel-searchable

Source: https://github.com/mozex/laravel-searchable/blob/main/CLAUDE.md

Defines the available composer scripts for linting, static analysis, type coverage, and Pest tests. Use these to run the full suite or individual checks during development.

```bash
composer test          # lint + phpstan + type-coverage + pest
composer test:unit     # pest only
composer test:types    # phpstan only
composer test:lint     # pint --test (check only)
composer lint          # pint (fix)
```

--------------------------------

### Public call forms for Comment::search()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Shows the public call forms with named parameters, demonstrating how to restrict columns, include/exclude columns, override external limit, disable relevance ordering, and set max terms.

```php
Comment::search('laravel')                                            // all searchableColumns()
Comment::search('laravel', in: ['title', 'body'])                     // only these columns
Comment::search('laravel', include: ['slug'])                          // searchableColumns + slug
Comment::search('laravel', except: ['author.name'])                    // searchableColumns − author.name
Comment::search('laravel', externalLimit: 200)                         // cross-db key cap override
Comment::search('laravel', orderByRelevance: false)                    // no ORDER BY added
Comment::search('laravel', maxTerms: 25)                               // term-split cap override
```

--------------------------------

### scope

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Static method to apply relevance sorting to a Filament table query, using the Livewire component's search and sort state.

```APIDOC
## `scope(Builder $query, HasTable $livewire, bool $isResolvingRecord = false): Builder`

### Description
Applies relevance sorting to a Filament table query when enabled and not resolving an individual record. It reads the current search and sort column from the Livewire component and delegates to `apply()`.

### Method
`scope` (static method)

### Signature
`public static function scope(Builder $query, HasTable $livewire, bool $isResolvingRecord = false): Builder`

### Parameters
- **$query** (`Builder<Model>`) - Required - The table's query being modified.
- **$livewire** (`Filament\Tables\Contracts\HasTable`) - Required - The table's Livewire component; provides `getTableSearch()` and `getTableSortColumn()`.
- **$isResolvingRecord** (`bool`) - Optional (default: `false`) - When `true` (Filament resolving an individual record, e.g. for relation managers), ranking is skipped.

### Return Type
`Builder<Model>` - The same query, possibly with relevance `ORDER BY` keys added.

### Example
```php
use Mozex\Searchable\Filament\RelevanceSort;

// Typically called from a Filament table's modifyQueryUsing hook.
$query = RelevanceSort::scope($query, $livewire);
```
```

--------------------------------

### Call applySearch() directly to bypass search() conflicts

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Invokes the package's scope directly via applySearch() when $query->search() won't reach it—either because a custom Eloquent Builder owns search() (e.g., Corcel's PostBuilder) or because a parent model already declares scopeSearch with a different signature. The example passes the query, the search term, and an 'in' option to restrict the search to the 'title' column.

```php
$query = Product::query();
$query->getModel()->applySearch($query, 'term', in: ['title']);
$results = $query->get();
```

--------------------------------

### RelevanceSort::register()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Static method to register the global Filament table configuration hook.

```APIDOC
## `register(): void`

### Description
Registers a global Filament table configuration hook that attaches the `scope()` method as a query modifier on every table, ranking Searchable-model tables by relevance while a search is active.

### Method
`register`

### Signature
```php
public static function register(): void
```

### Parameters
None.

### Return Type
`void`

### Example
```php
// Normal usage: nothing to call — the service provider registers this at boot.

// Manual re-registration in a custom provider (only if you disabled the automatic boot hook):
RelevanceSort::register();
```
```

--------------------------------

### Column Filtering with search() parameters

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Shows how to override or adjust the searched columns per query using the `in`, `include`, and `except` parameters. All three parameters accept a string or an array.

```php
// Search only specific columns (ignores searchableColumns)
Post::search('term', in: ['title', 'body'])->get();

// Add extra columns on top of searchableColumns
Post::search('term', include: ['slug'])->get();

// Exclude specific columns from searchableColumns
Post::search('term', except: ['author.name'])->get();

// Combine them
Post::search('term', include: ['slug'], except: ['body'])->get();
```

--------------------------------

### searchableColumns()

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-trait.md

Documentation for the searchableColumns() method of the Searchable trait, including its signature, return type, and column descriptor formats.

```APIDOC
## `searchableColumns()`

### Description
Returns the list of searchable column descriptors for the model. The default implementation returns an empty array, and models are expected to override it. The order of the returned array defines relevance priority: a hit in an earlier column outranks a hit in a later one.

### Method
`searchableColumns()`

### Signature
```php
public function searchableColumns(): array
```

### Parameters
None.

### Return Type
`array<int, string>` — the list of searchable column descriptors.

### Column Descriptor Formats
Each string is classified by the trait's type detection (`isRelationColumn()`, `isMorphColumn()`, `isMorphToColumn()`, `isExternalRelation()`, `isExternalMorph()`).

| Format | Type | Example |
|---|---|---|
| `column` | direct column | `'title'` |
| `relation.column` (dot notation; last segment is the column, everything before it the relation chain) | relation, any depth | `'author.name'`, `'author.company.name'` |
| `relation:morphType.column` (colon + dot) | morph relation (target type named explicitly) | `'commentable:post.title'`, `'commentable:post.author.name'` |
| any of the above where the related model's connection differs from the model's connection | external (cross-database) | auto-detected at query time |

A `MorphTo` relation written in plain dot notation (`'commentable.title'`) cannot resolve to a single related model and is **skipped** (in both filtering and ranking) rather than searched; use the typed colon syntax instead.

### Example
```php
use Mozex\Searchable\Searchable;
use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    use Searchable;

    public function searchableColumns(): array
    {
        return [
            'body',                       // direct column
            'author.name',                // BelongsTo
            'tags.name',                  // HasMany / BelongsToMany
            'commentable:post.title',     // morph target type: post
            'commentable:post.author.name', // nested inside the morph target
        ];
    }
}
```
```

--------------------------------

### applySearch with in and except parameters

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Shows that `applySearch` accepts the same parameters as the scope, including `in` and `except` to restrict or exclude columns.

```php
$query->getModel()->applySearch($query, 'term', in: ['title', 'body']);
$query->getModel()->applySearch($query, 'term', except: ['author.name']);
```

--------------------------------

### Scoping search in Livewire/controllers

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Scopes a search query to the authenticated user's projects, excluding specific columns from the search, and paginates the results. Place orderByDesc('updated_at') before search() to keep recency as the primary sort; placing it after makes relevance primary with updated_at as the tiebreaker.

```php
$results = auth()->user()
    ->projects()
    ->orderByDesc('updated_at')  // primary sort; relevance breaks ties
    ->search($this->search, except: ['user.name', 'user.email'])
    ->paginate();
```

--------------------------------

### Custom orderBy before search()

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Adds your own `orderBy()` before `search()` so your column is the primary sort and relevance is the tiebreaker. Calling `orderBy()` after `search()` flips the roles.

```php
// created_at drives the order, relevance only breaks ties
Post::query()->orderByDesc('created_at')->search('laravel')->get();
```

--------------------------------

### isEnabled() checks $enabled flag and config key

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/relevance-sort.md

Determines whether relevance sorting is active. Returns false if the static $enabled flag is false, otherwise returns the value of the 'searchable.filament.relevance_sort' config key (defaulting to true). The config key is read on every query, so runtime changes take effect without rebooting.

```php
protected static function isEnabled(): bool
{
    if (! self::$enabled) {
        return false;
    }

    return (bool) Config::get('searchable.filament.relevance_sort', true);
}
```

--------------------------------

### getResults() method implementation

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/global-search-provider.md

Implements the getResults() method that builds global search results by iterating over resources, sorting them by getGlobalSearchSort(), skipping those that cannot globally search, and using either the package's searchable results or Filament's native results. Returns a GlobalSearchResults object with categories for resources that have results.

```php
public function getResults(string $query): ?GlobalSearchResults
{
    $builder = GlobalSearchResults::make();

    $resources = Filament::getResources();

    usort(
        $resources,
        fn (string $a, string $b): int => ($a::getGlobalSearchSort() ?? 0) <=> ($b::getGlobalSearchSort() ?? 0),
    );

    foreach ($resources as $resource) {
        if (! $resource::canGloballySearch()) {
            continue;
        }

        $resourceResults = $this->hasSearchableTrait($resource)
            ? $this->getSearchableResults($resource, $query)
            : $resource::getGlobalSearchResults($query);

        if (! $resourceResults->count()) {
            continue;
        }

        $builder->category($resource::getPluralModelLabel(), $resourceResults);
    }

    return $builder;
}
```

--------------------------------

### Dynamic column composition from related models

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Composes searchable columns by merging the current model's columns with those of a related Faq model, prefixing each related column with 'faqs.' to enable searching across the relationship.

```php
public function searchableColumns(): array
{
    return [
        'name',
        'slug',
        ...collect((new Faq)->searchableColumns())
            ->map(fn (string $column): string => 'faqs.' . $column)
            ->toArray(),
    ];
}
```

--------------------------------

### Basic usage: Searchable trait and search()

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Add the Searchable trait to a model and define searchable columns, then call the search method. The search wraps conditions in a WHERE (... OR ...) group, so it composes with existing query constraints.

```php
use Mozex\Searchable\Searchable;

class Comment extends Model
{
    use Searchable;

    public function searchableColumns(): array
    {
        return [
            'body',                          // direct column
            'author.name',                   // BelongsTo relation
            'tags.name',                     // HasMany relation
            'commentable:post.title',        // morph relation
            'commentable:video.name',        // another morph type
        ];
    }

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }

    public function commentable(): MorphTo
    {
        return $this->morphTo();
    }
}
```

```php
// Shortest form, searches all configured columns
Comment::search('laravel')->get();

// Chain with other query constraints
Comment::query()
    ->where('published', true)
    ->search($request->input('q'))
    ->paginate();
```

--------------------------------

### Define global searchable attributes on resources

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Define getGloballySearchableAttributes() on each resource to control which columns global search uses. Return all searchable columns or a subset. Resources without this method are excluded from global search.

```php
class CourseResource extends Resource
{
    // Use everything the model declared as searchable
    public static function getGloballySearchableAttributes(): array
    {
        return (new Course)->searchableColumns();
    }
}

class PostResource extends Resource
{
    // Or limit global search to a subset, even though
    // the Post model has more columns in searchableColumns()
    public static function getGloballySearchableAttributes(): array
    {
        return ['title', 'author.name'];
    }
}
```

--------------------------------

### registerFilamentRelevanceSort() method

Source: https://github.com/mozex/laravel-searchable/blob/main/_autodocs/api-reference/searchable-service-provider.md

Registers the global relevance sort (see RelevanceSort) only when Filament's Table class exists.

```php
protected function registerFilamentRelevanceSort(): void
{
    if (! class_exists(Table::class)) {
        return;
    }

    RelevanceSort::register();
}
```

--------------------------------

### Multi-word search with Author::search

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Demonstrates multi-word search where each whitespace-separated term must match somewhere across the searchable columns, but terms may appear in different columns. The first query finds "Jane Doe" regardless of order; the second matches "Jane" in the name column and "acme.com" in the email column.

```php
Author::search('Doe Jane')->get();          // finds "Jane Doe"; order doesn't matter
Author::search('Jane acme.com')->get();     // "Jane" in name, "acme.com" in email
```

--------------------------------

### Register SearchableGlobalSearchProvider on Filament panel

Source: https://github.com/mozex/laravel-searchable/blob/main/resources/boost/skills/searchable-development/SKILL.md

Registers the SearchableGlobalSearchProvider on a Filament panel. This provider passes each resource's getGloballySearchableAttributes() as the in: filter to the model's search scope.

```php
use Mozex\Searchable\Filament\SearchableGlobalSearchProvider;

return $panel->globalSearch(SearchableGlobalSearchProvider::class);
```

--------------------------------

### Configure advancedSearchable with except parameter

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Pass parameters like 'except' to the advancedSearchable() macro to exclude specific columns from the search.

```php
TextColumn::make('title')
    ->advancedSearchable(except: ['author.name'])
    ->sortable(),
```

--------------------------------

### Direct columns in searchableColumns()

Source: https://github.com/mozex/laravel-searchable/blob/main/README.md

Define plain column names on the model's own table as searchable columns.

```php
public function searchableColumns(): array
{
    return ['title', 'body', 'slug'];
}
```
Tokens:
Raw