Skip to content
er2esPublic

About

Fuzzphony is a PostgreSQL-native search layer for PHP and Symfony: typo-tolerant, accent-insensitive, ranked full-text search with filters and a real query language, without Elasticsearch, Meilisearch or any other service. Tables are never altered; a sidecar index table sits next to them.

Topics

Resources

Contributing

Security policy

Stars

18 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,259 Commits

Folders and files

Repository files navigation

Fuzzphony: fuzzy search, in perfect harmony with your database.

Fuzzphony

CI codecov PHPStan level max Mutation score OpenSSF Scorecard OpenSSF Best Practices

Packagist Version PHP PostgreSQL 15 | 16 | 17 | 18 Symfony 7.4 LTS | 8.1 License: MIT

Fuzzy search, in perfect harmony with your database.

Fuzzphony is a small, relevant alternative to Elasticsearch and Meilisearch for PHP and Symfony applications that already run PostgreSQL: typo-tolerant, accent-insensitive, ranked full-text search with filters, facets and a query language. It never alters your tables. The index lives in a sidecar table next to them, in the database you already run, so there is no search service to add, feed or keep in step.

  • Consistent. The index is in the same PostgreSQL as your data: no dual write, no second system that can disagree. With sync: trigger a row and its index entry change in one transaction (no lag); with the queue, within one worker batch. A search runs inside your transaction and sees what it sees.
  • Secure. Authorization is built in: a tenant-scoped index refuses a search without a tenant, a field can be granted to a role, and a field a viewer may not see is not matched, ranked, highlighted, counted or suggested from. Tests prove a hidden field's content cannot change a restricted viewer's results. A search that names no actor is made as the current user.
  • Fast and small. Common searches answer in milliseconds on half a million rows, and the whole index costs a part of the table it indexes (what each option costs in disk).
$result = $fuzzphony->in(Product::class)
    ->query('wireles mouse -cable')          // typo, exclusion
    ->where('price', '<=', 20_000)
    ->where('in_stock', true)
    ->highlight('name')
    ->get();

foreach ($result as $hit) {
    echo $hit->id, ' ', $hit->score, ' ', $hit->highlights['name'];   // "<mark>Wireless</mark> mouse"
}

Status: pre-1.0 (v0.12.8). The API may still change before 1.0; breaking changes are listed in the CHANGELOG and explained in UPGRADE.md.

Try the demo

A full Symfony app on a seeded catalogue of 500 000 products (about a minute to index), with an ERP-like data set and a header search box over all indexes, in one command:*

git clone https://github.com/er2es/fuzzphony
cd fuzzphony/demo && docker compose up --build    # http://localhost:8000

If Docker stops with additional privileges requested, set export BUILDX_BAKE_ENTITLEMENTS_FS=0 (bash) or $env:BUILDX_BAKE_ENTITLEMENTS_FS=0 (PowerShell) first (why).

* The demo, the documentation (docs/), the tests and the benchmarks live in the Git repository only: composer require fuzzphony/fuzzphony installs just the library (src/). See the demo README (Windows, the large profile, security defaults; a local showcase, not a production template) and the screenshots.

Why

Behind most search boxes is a LIKE '%…%' that misses hedphones, creme and drills, reads the whole table and ranks nothing. The usual fix is a search cluster: one more service to run, sync, back up and secure, and one more copy of your data. Fuzzphony does the search inside PostgreSQL instead, without changing your schema.

A good fit when:

  • The database is not yours to change (a legacy system, an ERP, tables another team owns): no column is added; with schema: fuzzphony not even a table lands in your schema.
  • You are replacing LIKE in admin panels, back offices, CRMs and support tools, or one more service is one too many.
  • The data must stay under the same backups and roles, and search must be as fresh as the data (trigger mode: same transaction).
  • You run a shared-schema multi-tenant SaaS (the tenant filter is enforced on every query), or need a rate limit, index authorization and fields only some viewers may search, and want to know what people search for and do not find.
  • A record has several values (addresses, phone numbers) that should be found by any value, or ranked by the best single one.
  • Your content is multilingual: stemming for 28 languages, accent folding (kavefozo finds Kávéfőző).

Measured up to 1,000,000 documents per index (a typical search takes milliseconds to about a hundred; the commonest words, many-word queries, typo searches on wide indexes and viewers with granted fields take longer, see benchmarks and limitations); beyond a few million documents per index, measure first. A search is an ordinary read query, so throughput is that of your PostgreSQL and its connection pool. Not for analytics-style aggregations, semantic or vector search, or a database other than PostgreSQL.

LIKE '%…%' Fuzzphony External engine
Typos (hedphones) ✘ ✔ trigram fallback ✔
Accents (creme → crème) ✘ ✔ unaccent ✔
Stemming (drills → drill) ✘ ✔ PostgreSQL's 28 Snowball languages ✔
Relevance ranking + field weights ✘ ✔ explainable ✔
Extra service to run, sync and secure – none yes
Transactional consistency with your data ✔ ✔ (trigger mode) eventual

Requirements

  • PHP 8.4+
  • PostgreSQL 15+ with the pg_trgm and unaccent extensions. Both ship with PostgreSQL, but a superuser or the database owner must enable them per database:
    CREATE EXTENSION IF NOT EXISTS pg_trgm;
    CREATE EXTENSION IF NOT EXISTS unaccent;
  • Optional: Symfony 7.4+ and Doctrine (DBAL 4.2+, ORM 3.3+) for the bundle. CI tests every Symfony release the ^7.4 || ^8.1 constraint allows (7.4 LTS and 8.1 today) and the next minor as an early warning; a release Symfony no longer maintains leaves the constraint and CI together.

bin/console fuzzphony:doctor checks all of this and prints the fix for anything missing.

Install

composer require fuzzphony/fuzzphony

For Symfony, add Fuzzphony\Bundle\FuzzphonyBundle::class => ['all' => true] to config/bundles.php. The bundle uses your Doctrine DBAL connection (fuzzphony.connection, default default).

Upgrading: composer update, then bin/console fuzzphony:schema --apply, fuzzphony:reindex <index> when the doctor asks, and fuzzphony:doctor (details per release in UPGRADE.md).

Quickstart (Symfony)

  1. Mark an entity as searchable:

    use Fuzzphony\Core\Attribute\{Searchable, SearchField, SearchFilter};
    
    #[ORM\Entity]
    #[Searchable(language: 'english')]
    class Product
    {
        #[ORM\Id, ORM\Column] public int $id;
    
        #[ORM\Column, SearchField('A', fuzzy: true)]  public string $name;
        #[ORM\Column, SearchField('C')]               public string $description;
        #[ORM\Column, SearchFilter]                   public int $price;       // type inferred
        #[ORM\Column, SearchFilter]                   public bool $inStock;    // filter "in_stock"
    }

    Or let the wizard write the definition for an existing table, joins included: bin/console fuzzphony:wizard product --try.

  2. Create the index and fill it:

    bin/console fuzzphony:schema            # review the SQL first (nothing is executed)
    bin/console fuzzphony:schema --apply    # or: --dump-migration=migrations
    bin/console fuzzphony:reindex           # built next to the live index, swapped in; resumable
    bin/console fuzzphony:doctor            # verify everything, with fixes
    bin/console fuzzphony:search products 'wireles mouse' -w "price<=20000"
  3. Inject Fuzzphony\Core\Fuzzphony and search as in the example at the top. Fuzzphony\Bridge\Doctrine\EntityLoader turns results into entities with one query, keeping the ranking order.

By default, triggers queue changed rows and bin/console fuzzphony:worker keeps the index current (see sync modes). Without Symfony, define indexes with IndexDefinition::builder() and a PdoConnection (plain PHP setup).

Query syntax

Search text from end users never throws. Malformed input is repaired and reported in $result->warnings. Developer mistakes, such as an unknown filter, do throw, with a suggestion.

Syntax Meaning
wireless mouse both words (AND is implicit; AND also works)
"wireless mouse" exact phrase
mouse OR trackpad, mouse | trackpad either
-cable, NOT cable, !cable exclude
keyb* prefix
brand:logitech, name:"mx master" only in that field, typos included (an unknown field searches every field, with a warning)
(mouse OR trackpad) -cable grouping

Typos are tolerated per word (one from 4 letters, two from 8). A multi-word query that finds nothing drops the words that match nothing and says so. Details: Searching.

Documentation

The documentation index lists every page with a reading order:

Security

  • Search text is parsed by Fuzzphony and bound as a parameter; identifiers come only from validated definitions.
  • Highlights are HTML-escaped (only <mark> remains); $result->warnings and $result->interpretedAs are plain text that may quote the user: escape them.
  • Query length, term count, nesting depth and candidate sets are capped. Also set a PostgreSQL statement_timeout for the application's role.
  • Index definitions (fromQuery(), watch() SQL, names) are trusted developer input: never build them from user input.
  • Opt-in guards protect who searches: rate limit, index authorization and field-level granted (Security; row-level authorization is out of scope).

Report vulnerabilities privately: see SECURITY.md.

Known limitations and roadmap

Typo tolerance is trigram-based (it cannot tell a typo from a similar word), and a word with more matches than limits.candidates is ranked over its best matches with a lower-bound total: see docs/limitations.md. PostgreSQL only before 1.0; v1.0.0 is the stable API and the backward-compatibility promise (roadmap).

Contributing and license

Tests need PostgreSQL; docker compose up -d in the repository root starts one. composer qa runs php-cs-fixer, PHPStan (level max) and the unit tests. The unit and integration suites cover 100% of the lines in src/; CI fails below 90%. See CONTRIBUTING.md.

Licensed under the MIT license.

About

Fuzzphony is a PostgreSQL-native search layer for PHP and Symfony: typo-tolerant, accent-insensitive, ranked full-text search with filters and a real query language, without Elasticsearch, Meilisearch or any other service. Tables are never altered; a sidecar index table sits next to them.

Topics

Resources

Contributing

Security policy

Stars

18 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages