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: triggera 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.
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:8000If 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.
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: fuzzphonynot even a table lands in your schema. - You are replacing
LIKEin 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 (
triggermode: 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 (
kavefozofindsKá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 |
- PHP 8.4+
- PostgreSQL 15+ with the
pg_trgmandunaccentextensions. 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.1constraint 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.
composer require fuzzphony/fuzzphonyFor 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).
-
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. -
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"
-
Inject
Fuzzphony\Core\Fuzzphonyand search as in the example at the top.Fuzzphony\Bridge\Doctrine\EntityLoaderturns 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).
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.
The documentation index lists every page with a reading order:
- Index definitions: attributes, YAML, builder, bundle configuration.
- Searching: the builder, query syntax, typo tolerance, "did you mean", facets, federated search.
- Migrating from
LIKE, and recipes backed by tests: admin panel, shop, multi-tenant SaaS. - Ranking, languages, sync, multi-tenancy.
- Search log and analytics, security, database roles.
- Console commands, observability, integrations.
- Benchmarks, known limitations, architecture and ADRs, roadmap.
- 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->warningsand$result->interpretedAsare 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_timeoutfor 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.
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).
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.