Download the PHP package ashiqfardus/laravel-fuzzy-search without Composer

Laravel Fuzzy Search

A powerful, zero-config fuzzy search package for Laravel with fluent API. Works with all major databases without external services.

Demo: laravel-fuzzy-search-demo - See the package in action!

Documentation: Upgrade v1→v2

Features

Table of Contents

• Installation
• Quick Start
• Search Algorithms
• Field Weighting & Scoring
• Text Processing
• Result Presentation
• Performance & Indexing
• BM25 Inverted Index
• Extended Search Syntax
• Scout Driver
• Pagination
• Reliability & Safety
• Events
• Configuration
• CLI Tools
• Performance & Scaling
• Algorithm × Database Compatibility
• Testing
• Requirements

Installation

That's it! Zero configuration required. Start searching immediately.

Optionally publish the config file:

If you plan to use the BM25 inverted index (recommended for 10k+ rows), also run:

Upgrading from v1.x? There are breaking changes — result rankings and _score values may shift. Run the scanner to find affected code, then follow the full guide.

→ Full upgrade guide

Quick Start

Zero-Config Search

How auto-detection works: The package automatically detects common column names in this priority order:

• name, title (weight: 10)
• email, username (weight: 8)
• first_name, last_name (weight: 7)
• description, content, body (weight: 5)
• bio, summary, excerpt (weight: 3)
• slug, sku, code (weight: 2-6)

If none of these exist, it falls back to the model's $fillable columns.

Manual Column Configuration

You can manually specify which columns to search and their weights:

Fluent API

Eloquent & Query Builder Support

Search Algorithms

Available Algorithms

⚠️ metaphone requires one-time setup. Unlike the other algorithms, it searches against a precomputed {column}_metaphone shadow column. Calling using('metaphone') without it throws RuntimeException. Run the three commands shown in Shadow Columns once per searchable column.

Shadow Columns

Most algorithms compute their score on the fly during the SQL query. Metaphone is the exception — PHP's metaphone() function isn't available in SQL, so the package precomputes the phonetic code on every save and stores it in a sibling column.

For a users table with a name column, that means adding a name_metaphone column right next to it. Each row's name_metaphone holds the phonetic code (e.g. Stephen → STFN, Steven → STFN, Stefan → STFN). At search time, the query is a simple equality check against the precomputed code — fast, no per-row PHP calls.

Setup (one-time per column):

After this, the SearchableObserver keeps name_metaphone in sync automatically on every save() and update().

What gets generated:

Safety guards in the command:

• The model must exist and be an Eloquent model.
• The model must live in your app namespace — vendor/framework classes are rejected.
• The column name is sanitized to [a-zA-Z0-9_] only — blocks SQL injection through the argument.

Typo Tolerance

Multi-Word Token Search

In-Memory Mode

Supported methods: search, searchIn, take, skip, withRelevance, get. Any other SearchBuilder method (e.g. extended(), using(), preset(), paginate()) will throw a \BadMethodCallException to prevent silent failures.

Field Weighting & Scoring

Weighted Columns

Relevance Scoring

Prefix Boosting

Partial Match Support

Custom Scoring Hooks

Recency Boost

Boost newer records in search results:

Search Suggestions / Autocomplete

Get autocomplete suggestions based on search term:

"Did You Mean" Spell Correction

Get alternative spellings when search has typos:

Multi-Model Federation Search

Search across multiple models simultaneously:

Search Analytics

Get detailed analytics about your search configuration:

Text Processing

Stop-Word Filtering

Synonym Support

Language / Locale Awareness

Unicode & Accent Insensitivity

Result Presentation

Highlighted Results

Debug / Explain-Score Mode

Performance & Indexing

Async Indexing (Queue Support)

Redis / Cache Support

BM25 Inverted Index

For large tables (10k+ rows), the BM25 inverted index provides ranked, fast results without scanning the full table.

How It Works

The indexing system has two parts:

Part 1 — One-time initial build. Run once after install (or after a schema change):

Part 2 — Automatic incremental updates. After the initial build, every time a model is saved or deleted, the package dispatches a small queue job that re-indexes just that one row. No cron jobs or manual work needed.

The flow when a record is saved:

Database Tables

Production Setup

Step 1 — Run migrations:

Step 2 — Enable indexing in config:

Step 3 — Declare searchable columns on your model:

Step 4 — Build the initial index:

Step 5 — Start a queue worker:

Supervisor config (/etc/supervisor/conf.d/fuzzy-search-worker.conf):

For Laravel Horizon (Redis):

Usage

Note: useIndex() is an alias for useInvertedIndex(). The deprecated legacy search_index table from v1 is no longer used.

Limitation: The BM25 inverted index requires integer primary keys. Models with UUID/ULID primary keys are not currently supported — use the standard LIKE or Levenshtein paths for those.

Column weights and BM25: searchIn() weights are respected by the LIKE/Levenshtein scoring paths but are ignored by BM25. BM25 scores by term frequency and inverse document frequency only.

Artisan Commands

BM25 Tuning

Stemming (Optional)

Default: no stemming (NullStemmer). With NullStemmer, running only matches running, not run or ran.

To enable Porter stemming:

Supported languages: English, French, German, Spanish, Italian, Russian, Dutch, Portuguese, Swedish, Danish, Norwegian. You must rebuild the index after changing the stemmer.

Observer Auto-Attach

Adding the Searchable trait automatically registers observers via bootSearchable():

• SearchableIndexingObserver — listens to saved and deleted events. Queues an IndexModelJob to update the BM25 index. This is a no-op when indexing.enabled is false.
• SearchableObserver — listens to saved events and writes metaphone shadow columns if they exist. Safe when no shadow columns are configured — the observer silently exits.

No configuration is required for either observer until you enable those features.

Sync vs Async

For tests, set indexing.async = false so indexing happens synchronously:

Extended Search Syntax

Use Fuse.js-style operators inside your search string for precise control over matching.

Operators

Usage

Limits

Pagination with Extended Syntax

paginate() and cursorPaginate() are not compatible with extended() or searchBoolean() and will throw a BadMethodCallException. simplePaginate() works correctly.

Match Offsets & Blade Directive

Results with ->highlight() enabled include a _matches array:

For safe HTML rendering, use the @fuzzyHighlight Blade directive:

The directive automatically escapes user-supplied content and wraps matches in <mark> tags.

Scout Driver

The Scout engine adapter is bundled in this package and registers automatically when laravel/scout is installed. No separate driver package is required.

Setup

In .env:

Build the index:

Usage

Add both traits to your model:

Relevance Scores

Results include _score (BM25 relevance, higher = more relevant):

Authorization

Scout's default behavior bypasses Eloquent global scopes. Apply them explicitly:

How It Works

The Scout engine wraps the same IndexManager + Bm25Scorer used by Model::search()->useInvertedIndex(). There is no separate index — it reads from the same fuzzy_index_* tables.

Pagination

Stable Ranking

Pagination Methods

Note: paginate() and cursorPaginate() are not compatible with extended() or searchBoolean(). Use simplePaginate() or get() with those.

Reliability & Safety

Fallback Search Strategy

Rate-Limit Friendliness

SQL Injection Safety

All queries use parameterized bindings. Search terms are automatically sanitized.

Exception Handling

Available Exceptions:

• LaravelFuzzySearchException - Base exception (catch all)
• EmptySearchTermException - Search term is empty
• InvalidAlgorithmException - Invalid algorithm specified
• InvalidConfigException - Configuration error
• SearchableColumnsNotFoundException - No searchable columns found

Events

FuzzySearchExecuted

Fired after every ->get() or ->paginate() call. Useful for monitoring search latency and volume in production.

Properties:

• searchTerm (string) — the user's query
• columns (array) — columns being searched
• algorithm (string) — algorithm used: simple, fuzzy, levenshtein, soundex, metaphone, trigram, similar_text, or bm25
• candidateCount (int) — rows fetched from SQL before scoring
• latencyMs (float) — total search time in milliseconds

Configuration

Config File

Config Presets

Presets are predefined search configurations for common use cases. Instead of manually configuring multiple options every time, use a single preset name.

Without preset (verbose):

With preset (clean):

Available Presets

Preset Configuration Reference

Using Presets

Override Preset Settings

Create Custom Presets

Per-Model Customization

CLI Tools

Indexing Commands

Benchmark & Debug Commands

Performance & Scaling

Algorithm Comparison

Measured Latency (100k-row MySQL 8.0 dataset)

Numbers measured on the live demo (commodity VPS, warm cache). Run php artisan demo:seed in the demo project to seed the same dataset.

At scale: The BM25 path uses an indexed term lookup — query time grows with the number of matching postings, not total row count. A well-maintained 1M-row index returns results in the same ~12–20 ms window as the 100k baseline.

When to Use BM25 vs LIKE

Use BM25 (useInvertedIndex()) when:

• Table has 10k+ rows
• Result ranking/relevance quality matters
• You have queue workers running
• Models use integer primary keys

Use LIKE / fuzzy when:

• Small tables (< 10k rows) — LIKE can be faster due to BM25 scoring overhead
• UUID/ULID primary keys
• You need column weights to affect ranking

max_candidates Tuning

For the LIKE/Levenshtein paths, SQL candidates are fetched then re-scored in PHP. The candidate set size is controlled by max_candidates (default: 1000). Lower this on large tables to reduce memory usage:

Recommended Optimizations

Key tips:

1. Use the BM25 index for tables with 10k+ rows
2. Enable caching for repeated searches
3. Limit columns — only search relevant fields
4. Use simple algorithm when typo tolerance isn't needed
5. Set max_candidates to prevent excessive memory usage on large tables
6. Use take() to cap result sets
7. Eager load relationships to avoid N+1 queries

Scaling Recommendations

Algorithm × Database Compatibility

This table shows what each algorithm does at the SQL level on each supported database. "Native" = the database's own function. "Pattern fallback" = PHP generates LIKE patterns.

Notes

• use_native_functions in config/fuzzy-search.php gates optional DB extensions. MySQL SOUNDEX() is built-in and always active — no flag needed. The flag is only relevant for: Levenshtein UDF (MySQL), pg_trgm/fuzzystrmatch (PostgreSQL), unaccent (PostgreSQL).
• Levenshtein UDF (MySQL): Not installed by default. See this gist or your DB package manager.
• pg_trgm (PostgreSQL): CREATE EXTENSION IF NOT EXISTS pg_trgm;
• fuzzystrmatch (PostgreSQL): CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;
• unaccent (PostgreSQL, for accentInsensitive()): CREATE EXTENSION IF NOT EXISTS unaccent; + use_native_functions=true
• MySQL accent insensitive: Use utf8mb4_unicode_ci or utf8mb4_0900_ai_ci collation on the column.
• Metaphone shadow column: Run php artisan fuzzy-search:add-shadow-column {Model} {column} --type=metaphone then php artisan migrate.

PHP-Side Scoring

Regardless of algorithm, after SQL candidates are fetched:

1. similar_text() and levenshtein() run in PHP on each candidate.
2. Results are re-sorted by the combined PHP score (higher = better).
3. limit/offset is applied on the PHP-sorted collection (not in SQL).

Top-N results are always the most relevant N from the candidate set (not just the first N SQL rows). Candidate set size is controlled by max_candidates (default: 1000).

Pagination note: paginate() and simplePaginate() use DB-level pagination and score within the current page only. For globally-ranked pagination across all pages, use the BM25 inverted index.

Testing

Requirements

• PHP 8.1 or higher
• Laravel 9.x, 10.x, 11.x, 12.x, or 13.x
• Any supported database

License

MIT License. See LICENSE for more information.

Credits

• Md Asikul Islam

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.