Fuzzy Similarity

Fuzzy (string-based) similarity for Laravel Eloquent models: compare two records, or rank a collection against a query, by how closely their text matches.

It measures how the text is written, not what it means. For meaning-based (vector) similarity see x-laravel/embedding; the two packages can be used on the same model side by side.

How It Works

• Add the FuzzyComparable trait and declare the compared columns with #[FuzzyOn]
• Define one or more named slots per model; different models are compared through the same slot name (one model's name against another's title)
• Both sides are normalized first — by default to lower-case ASCII, so Crème Brûlée equals creme-brulee and São Paulo equals Sao Paulo
• Scores range from 0.0 to 100.0; the algorithm is configurable per call or globally

Requirements

• PHP ^8.4 with intl and mbstring
• Laravel ^12.0 | ^13.0

Installation

composer require x-laravel/fuzzy-similarity

Optionally publish the config file:

php artisan vendor:publish --tag=fuzzy-similarity-config

Setup

use Illuminate\Database\Eloquent\Model;
use XLaravel\FuzzySimilarity\Attributes\FuzzyOn;
use XLaravel\FuzzySimilarity\Concerns\FuzzyComparable;
use XLaravel\FuzzySimilarity\Contracts\HasFuzzySimilarity;

#[FuzzyOn('name')]
#[FuzzyOn(['name', 'city'], slot: 'location')]
class Company extends Model implements HasFuzzySimilarity
{
    use FuzzyComparable;
}

#[FuzzyOn('title')]
class Article extends Model implements HasFuzzySimilarity
{
    use FuzzyComparable;
}

A slot's columns are joined with a space; blank values are skipped. Override toFuzzyText(string $slot) to build the text yourself.

Usage

Compare two records

$company->fuzzySimilarityTo($otherCompany);             // default slot
$company->fuzzySimilarityTo($otherCompany, slot: 'location');
$company->fuzzySimilarityTo($article);                  // Company name vs Article title
$company->fuzzySimilarityTo('Acme Corporation');        // plain string
$company->fuzzySimilarityTo('Corporation Acme', algorithm: 'token_set');

Rank a collection

$ranked = Company::rankByFuzzy($candidates, 'Acme Corporation', limit: 20, threshold: 40.0);

$ranked->first()->fuzzy_score; // 0.0 – 100.0

The query may also be a model. Each ranked model gets a fuzzy_score attribute; ranking happens in PHP, so pass an already narrowed-down collection.

Compare strings directly

use XLaravel\FuzzySimilarity\FuzzySimilarity;

app(FuzzySimilarity::class)->compare('São Paulo', 'sao-paulo'); // 100.0

Algorithms

Add your own by implementing XLaravel\FuzzySimilarity\Contracts\Algorithm and registering it under algorithms in the config, or pass its class name as algorithm:.

Normalizers

Set normalizer in the config to any class implementing XLaravel\FuzzySimilarity\Contracts\Normalizer.

AsciiNormalizer keeps the last 10,000 results in a per-process cache, so a name compared against thousands of candidates is folded once, and long-running processes (Octane, queue workers) reuse results across requests. When the cache is full the oldest entry is dropped. Call AsciiNormalizer::flushCache() to empty it.

Testing

docker compose --profile php84 run --rm php84
docker compose --profile php85 run --rm php85

License

MIT