Search is one of those application features that begins with a simple SQL query and gradually becomes an architectural decision.

A small product catalog may initially use LIKE or ILIKE to find matching records. As the catalog grows, users begin expecting more: results ranked by relevance, tolerance for spelling mistakes, accent-insensitive matching, filtering, and suggestions when a search returns nothing.

The conventional response is often to introduce a dedicated search engine such as Elasticsearch or Meilisearch. These tools offer powerful capabilities, but they also introduce infrastructure, synchronization requirements, and another system that must be secured, monitored, and maintained.

Fuzzphony takes a different approach. It implements an application-oriented search layer directly on top of PostgreSQL, using its full-text search capabilities, trigram matching, and dedicated sidecar indexes.

Developed by Szabó József, the MIT-licensed PHP project is currently in its pre-1.0 development phase. Version 0.12.8 was released on November 15, 2026.

For this edition of PHP Projects Radar, we examined the repository, its architecture, integration examples, documented benchmarks, and known limitations to understand where Fuzzphony might be useful and where a separate search engine remains preferable.

The Problem with a Simple ILIKE Search

Consider a PHP application backed by PostgreSQL. Its product catalog contains an item named “Wireless Mouse”.

A conventional search might look like this:

SELECT id, name, price
FROM product
WHERE name ILIKE '%wireless%';

This is easy to understand and may be perfectly adequate for a small internal application.

But what happens when the user searches for “wireles mouse”, omitting an s? Or searches for “creme” when a product is named “crème”?

Ordinary substring matching does not automatically correct these differences. It also provides no sophisticated ranking model for deciding which of several matching products is most relevant.

PostgreSQL already includes capabilities that can help address these problems. Full-text search supports language-aware tokenization, stemming, and ranking. The pg_trgm extension adds similarity calculations based on groups of three characters.

Fuzzphony combines these capabilities behind a PHP API, adds configurable ranking and filtering, and manages the index structures required to make them usable in an application.

An Index Beside Your Tables, Not Another Search Server

The most interesting design decision is the use of a sidecar index.

Instead of adding search-specific columns to existing application tables, Fuzzphony creates separate index tables within PostgreSQL.

These tables contain normalized search data, weighted full-text vectors, fuzzy-search representations, filter values, and metadata needed by the search engine.

The application continues to own its original data model. The search structures remain separate, although they occupy storage and consume resources within the same PostgreSQL instance.

This architecture is particularly attractive for legacy databases, enterprise applications, and systems where modifying existing table definitions is difficult.

However, it is important to understand the distinction between not adding columns and making no database changes. Fuzzphony still needs to create its own schema objects and may install triggers on source tables to synchronize changes.

Organizations operating under strict database-change policies must therefore review the generated SQL and the privileges required for installation.

Inside the Search Architecture

The repository separates its implementation into four logical layers.

  • Core: Index definitions, query parsing, ranking configuration, synchronization, and search interfaces.
  • PostgreSQL Engine: SQL generation, full-text search, trigram matching, schema creation, and index maintenance.
  • Doctrine Bridge: Integration with database connections, object mapping, and entity synchronization.
  • Symfony Bundle: Configuration, dependency injection, console commands, API Platform integration, and user-interface components.

These are layers of one Composer package, not four independently installed libraries.

Another useful distinction is that Fuzzphony’s fuzzy search is lexical rather than semantic. It recognizes spelling similarities using trigrams; it does not understand concepts through language-model embeddings or vector similarity.

Searching for a misspelled product name is therefore a suitable use case. Finding conceptually similar documents that share few words is a different problem.

Installing Fuzzphony

The project’s current requirements include PHP 8.4 or later, PostgreSQL 15 or later, and the mbstring, PDO, and PDO PostgreSQL extensions.

PostgreSQL must also have pg_trgm and unaccent enabled in the target database:

CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS unaccent;

The extensions are distributed with PostgreSQL, although enabling them requires the appropriate database privileges.

Install the PHP package using Composer:

composer require fuzzphony/fuzzphony

For Symfony applications, the project provides a bundle that integrates with Doctrine DBAL and optional ORM functionality.

In an application using the bundle, a searchable entity can be configured using attributes.

Making a Product Entity Searchable

The following example follows the official Symfony integration approach. It assumes an existing Doctrine application and a Product entity mapped to a corresponding database table.

<?php

use Doctrine\ORM\Mapping as ORM;
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;

    #[ORM\Column]
    #[SearchFilter]
    public bool $inStock;
}

Here, the product name receives a higher search weight than its description. The name also participates in fuzzy matching.

Price and stock availability become filterable fields. In this example, price is assumed to be stored as an integer number of minor currency units rather than a floating-point amount.

After defining the index, the application must create the required database structures and populate the search index.

bin/console fuzzphony:schema

bin/console fuzzphony:schema --apply

bin/console fuzzphony:reindex

bin/console fuzzphony:doctor

The first command previews the proposed schema changes. This is particularly important for production databases where generated SQL should be reviewed before execution.

The reindex operation builds the searchable data. The doctor command checks configuration and database requirements, helping identify missing extensions, schema discrepancies, or synchronization concerns.

Searching with Typo Tolerance and Filters

Once the index is available, search queries use a fluent API.

<?php

$result = $fuzzphony
    ->in(Product::class)
    ->query('wireles mouse -cable')
    ->where('price', '<=', 20000)
    ->where('in_stock', true)
    ->highlight('name')
    ->get();

foreach ($result as $hit) {
    echo $hit->id . PHP_EOL;
}

The example searches for wireless mice despite a misspelling, excludes results matching cable, applies price and availability filters, and requests highlighting for the product name.

The query language supports more than individual keywords. It can express exclusions, phrases, alternatives, and other structured conditions, making it suitable for search interfaces that need more precision than a basic text field.

However, fuzzy matching introduces an unavoidable trade-off between recall and precision. A permissive similarity threshold may find more relevant misspellings but also introduce unrelated results.

For real applications, relevance should be evaluated against representative user queries and an expected-results dataset—not judged from one successful demonstration.

Keeping the Search Index Synchronized

A separate index, even when it resides in the same database, introduces a synchronization responsibility.

Fuzzphony provides four synchronization approaches.

  • Queue: The default mode. Database triggers enqueue changed identifiers, and a background worker refreshes the corresponding index entries.
  • Trigger: Index updates occur within the database write transaction, allowing changes to become searchable transactionally.
  • ORM: Doctrine listeners react to entity operations, although changes performed outside the ORM require separate consideration.
  • Manual: The application explicitly refreshes or rebuilds indexes, suitable for some batch-oriented workflows.

The distinction matters because queue mode introduces a period during which search results may lag behind the primary data.

Trigger mode reduces that delay, but synchronous index maintenance adds work to write transactions and can increase latency or contention.

Neither mode is universally preferable. The choice depends on update frequency, freshness requirements, database capacity, and the consequences of temporarily stale results.

Multi-Tenancy and Search Authorization

One of the more interesting developments in Fuzzphony is its attention to applications containing data belonging to multiple customers or organizations.

Its index definitions can declare a tenant field, requiring searches to identify the appropriate tenant. The project also supports actor-aware queries and configurable authorization controls for indexes and individual fields.

This is important because search functionality can expose sensitive data indirectly, even when a user cannot open the underlying document.

For example, a search result count, highlight, or spelling suggestion may reveal information about a document the user is not otherwise permitted to read.

Fuzzphony documents measures intended to prevent restricted fields from influencing unauthorized users’ search results. Its tenant-scoping rules also reject searches that omit the required tenant.

These protections require correct configuration. Index authorization and rate-limiting guards are not automatically enabled in every installation.

The project also acknowledges that tenant isolation is enforced at the library layer. Organizations requiring defense against direct SQL access should consider PostgreSQL row-level security on the index tables as an additional boundary.

For production adoption, isolation and authorization should be tested explicitly with users from different tenants and with fields containing deliberately sensitive test data.

What Do the Benchmarks Actually Show?

The repository includes a benchmarking tool comparing Fuzzphony with conventional PostgreSQL ILIKE queries.

One documented run used 200,000 products on PostgreSQL 17, measuring an initial cold request and the median of five subsequent warm requests.

For a simple search for “wireless”, the documented warm ILIKE request completed in approximately 1.3 milliseconds, while Fuzzphony took approximately 35.3 milliseconds.

For the misspelled term “hedphones”, however, ILIKE returned no matching results in approximately 171.7 milliseconds, while Fuzzphony returned results in approximately 41.8 milliseconds.

These figures come from the project’s own benchmark documentation. They have not been independently reproduced by PHP Magazine.

They also illustrate why performance comparisons require context. A simple substring query and a ranked, typo-tolerant search do not perform the same work or necessarily return equivalent results.

Fuzzphony introduces candidate limits and ranking thresholds to keep expensive searches bounded. As a consequence, very common words and complex queries may take longer, and some reported totals or facets may reflect the selected candidate population rather than an exhaustive scan of all possible matches.

The appropriate question is therefore not simply which query executes faster, but which system returns useful results within an acceptable latency and resource budget.

Trying the Official Demo

The repository includes a Symfony demonstration application with a generated product catalog. By default, its setup creates approximately 500,000 products and builds the corresponding search indexes.

Developers can run the demo locally using Docker:

git clone https://github.com/er2es/fuzzphony

cd fuzzphony/demo

docker compose up --build

After initialization, the application is accessible at http://localhost:8000.

The demo includes search relevance explanations, multilingual queries, ranking controls, an ERP-like dataset, synchronization examples, and security scenarios.

It is particularly useful because developers can inspect how results change when search weights or thresholds are adjusted.

The maintainers explicitly describe the demo as a local showcase rather than a production deployment template. It contains development settings and intentionally exposes diagnostic information. It should not be deployed publicly without significant hardening.

Where Fuzzphony Falls Short

Fuzzphony is not a universal replacement for Elasticsearch, Meilisearch, or other dedicated search systems.

First, it currently targets PostgreSQL exclusively. Teams using MySQL or another database cannot simply install it and retain the same architecture.

Second, complex fuzzy matching, ranking, and faceting consume resources in the application’s PostgreSQL database. That can be an advantage when removing an external service, but it also concentrates workloads on the database responsible for transactional operations.

Third, the project remains below version 1.0. Its documented API and internal implementation may change, and adoption should include a review of the upgrade guide and release history.

Finally, trigram matching has inherent limitations. Similar-looking words are not always semantically related, and very long text, common terms, complex queries, and restricted-field searches can create difficult ranking or performance cases.

LEAVE A REPLY

Please enter your comment!
Please enter your name here