README

Typo-tolerant fuzzy search for Eloquent models, ranked by similarity score, backed by PostgreSQL pg_trgm and a single GIN index per column. Designed to stay fast on millions of rows.

If your models also use larasup/localization, the same query transparently spans every translated language — one Team::query()->fuzzy('real') call finds rows whose Russian, English, German, … localised name matches the query.

Quick start

use Larasup\Search\Concerns\Searchable;

class Article extends Model
{
    use Searchable;

    protected array $searchable = ['title', 'body'];
}

Article::query()->fuzzy('postgers tutoriall')->limit(20)->get();
//      ^                          ^
//      |                          ranked by similarity DESC
//      composes with any other Eloquent scope

Each result row carries a virtual search_score attribute (0..1) so you can show match strength in the UI:

foreach ($articles as $article) {
    echo $article->title.' — '.round($article->search_score * 100).'%';
}

Indexing — required for performance

The package uses the % operator and the gin_trgm_ops opclass, both of which need a GIN index on every searchable column. Add the indexes in your own migration via the helper:

use Larasup\Search\Schema\TrigramIndex;

return new class extends Migration {
    public function up(): void
    {
        TrigramIndex::create('articles', 'title');
        TrigramIndex::create('articles', 'body');
    }

    public function down(): void
    {
        TrigramIndex::drop('articles', 'title');
        TrigramIndex::drop('articles', 'body');
    }
};

If you also enable localization search, add a single shared index on the localizations table:

TrigramIndex::create('localize_localizations', 'value');

The package's own migration enables the pg_trgm extension on the connection — so CREATE EXTENSION IF NOT EXISTS pg_trgm runs automatically the first time you migrate.

Localization integration

If your model uses larasup/localization:

use Larasup\Localization\Traits\Localizable;
use Larasup\Search\Concerns\Searchable;

class Team extends Model
{
    use Localizable, Searchable;

    const LOCALIZABLE = ['name'];           // 'name' is translated per locale
    protected array $searchable = ['name']; // and 'name' is searchable
}

A single Team::query()->fuzzy('реал')->get() then matches against:

• teams.name (the original column, e.g. English from your import)
• every translated value in localize_localizations for class_id = Team and key = 'name'

Columns that are in $searchable but not in LOCALIZABLE are searched only in the base column, never in the localizations table — so you can mix both kinds freely.

Configuration

Publish the config file (optional):

php artisan vendor:publish --tag=search-config

// config/search.php
return [
    'localization' => [
        'enabled' => env('SEARCH_LOCALIZATION_ENABLED', true),
        'table' => env('SEARCH_LOCALIZATION_TABLE', 'localize_localizations'),
    ],
];

The localization.table value should be the fully-qualified table name in your database — change it only if you've customised localize.table_prefix or moved the localizations table into a database schema.

Tuning the similarity threshold

pg_trgm filters out matches below pg_trgm.similarity_threshold (default 0.3). Tune it globally in postgresql.conf or per-session via:

SET pg_trgm.similarity_threshold = 0.2;  -- more lenient

A lower threshold returns more (noisier) matches, a higher one returns fewer (more confident) ones. The package does not override this setting — it relies on whatever Postgres is configured to use.

License

MIT.