Unaccent Search Laravel Package

Technical Evaluation

What this package is: kaveraa/unaccent-search is a small Laravel package that adds accent-insensitive ("unaccent") matching to search queries — i.e. ecole matches École. It is a utility library, not a platform component: no daemon, no queue worker, no external service.

Architecture fit: Good fit for a conventional Laravel app. It slots into the Eloquent/query-builder layer, so it composes with existing repositories and scopes rather than forcing a search-service rewrite. It is not a replacement for Scout/Meilisearch/Elasticsearch — it solves the single problem of diacritic folding in SQL-backed search. Treat it as a tactical improvement to LIKE-based search, not as a search architecture decision.

Integration feasibility: Low. Composer install, package auto-discovery, optionally publish config. A single engineer can evaluate and wire it into one endpoint inside a sprint.

Technical risk: Low-to-moderate, concentrated in two areas rather than in the code itself:

1. Maintainer concentration. Single-maintainer, small-audience package. Bus-factor risk is real; mitigate with a version pin and a standing option to vendor/fork (the code surface is small enough that forking is genuinely cheap).
2. Query-plan risk. The dominant failure mode for accent-folding in SQL is that wrapping a column in a function (unaccent(col), LOWER(...)) makes ordinary B-tree indexes unusable and silently converts indexed lookups into sequential scans. This does not show up in dev with 500 rows; it shows up in production with 5M.

Assessment of v2.0.4 specifically: No code change. The release contains only a README banner URL fix (pinned to a commit rather than main), a reflow of code comments into plain English, and CI expansion to PHP 8.5 / PHPUnit 13 on the dev side. From a risk standpoint this is a zero-impact release — no API changes, no behaviour changes, no deprecations, no migration. Its informational value is as a maintenance signal: the project is actively tended and is tracking the PHP release train ahead of the curve. The bilingual FR/EN release notes and the comment-rewrite-to-English suggest a francophone maintainer deliberately broadening the contributor base — mildly positive for long-term sustainability.

Key questions to put to the maintainer / spike:

• Which database engines are supported and tested (MySQL, PostgreSQL, SQLite, MariaDB)? Behaviour differs sharply: PostgreSQL has a native unaccent extension; MySQL relies on collation (utf8mb4_unicode_ci already folds accents in comparisons) and this package may be redundant or may conflict there.
• Does the package document an indexing strategy (functional index, generated column, or shadow normalized column)? If not, we own that problem.
• What is the supported Laravel/PHP matrix, and is PHP 8.5 CI-only or a supported runtime? (v2.0.4 says tests run on 8.5 — confirm it is not merely aspirational.)
• Test coverage and CI status; is there a changelog policy (semantic versioning honoured)?
• Licence and any attribution requirements.

Integration Approach

Stack fit: Standard Composer package for Laravel with service-provider auto-discovery. No PHP extensions required beyond what the app already has, unless it delegates to a database-side unaccent function — confirm in the spike. Works alongside existing code; does not require adopting a particular search abstraction.

Migration path: Deliberately non-invasive.

1. composer require kaveraa/unaccent-search on a branch; publish config if offered.
2. Apply it behind a config flag to a single low-traffic search endpoint.
3. Verify result parity via a side-by-side comparison of old vs. new result sets for a sample of real queries — accent handling changes what users see, and "extra results" can read as "worse relevance" to stakeholders even when it is technically more correct.
4. Only then extend to additional endpoints.

There is no schema migration introduced by the package itself, but see the caveat below: the performance workaround likely does require a schema change, and that change should be planned as part of the rollout rather than discovered after.

Compatibility: v2.0.4 is a drop-in from v2.0.3 — identical code. If we are already pinned to a 2.x line, adopting this patch is free; there is no reason to rush it and no reason to avoid it.

Sequencing (suggested):

• Sprint 1 — spike (2–3 days): install, one endpoint, measure. Query-plan the affected queries before and after. Decide on the indexing approach. Confirm DB engine support.
• Sprint 2 — hardening: add the functional/generated-column index if required; add regression tests asserting accent-folding behaviour so a future package bump cannot silently change results.
• Sprint 3 — rollout: behind flag, one endpoint at a time, with a result-quality review by the product owner for the primary search surface.
• Ongoing: pin the minor version; review on each release.

When not to integrate: if the target database is MySQL with a *_ci_unicode collation and search is already LIKE-based, the collation may already be doing this work and the package adds a dependency for no behavioural gain. Establish this before spending engineering time.

Operational Impact

Maintenance burden: Very low. No runtime infrastructure, no background jobs, no storage. Upgrades are Composer bumps. The package's own maintenance posture is healthy — v2.0.4 demonstrates CI currency (PHP 8.5, PHPUnit 13) even when no code changed, which is the behaviour you want from a small dependency.

Support model: Community-maintained by a single author. There is no vendor SLA and no commercial support tier. Our mitigation is procedural, not contractual: version pinning, a regression test suite that encodes the behaviour we depend on, and an explicit acceptance that forking is the fallback. Given the small code surface, a fork is a day of work, not a project.

Scaling characteristics: This is where operational attention belongs. Accent folding is a correctness feature with a performance cost:

• Function-wrapped predicates invalidate standard indexes. Without a functional index (PostgreSQL) or a generated/shadow normalized column (MySQL), search latency degrades roughly linearly with table size.
• Write amplification if a shadow column is used — acceptable, but it belongs in the design.
• Result-set size grows (more matches returned); pagination, rate limiting, and any downstream export of search results should be sanity-checked.
• Recommendation: set an explicit latency budget for the search endpoint before rollout and instrument it, so the regression is caught by us rather than by users.

Failure modes to plan for:

• Silent relevance drift. Accent folding changes ranking and result counts. Without a parity check against production query samples, this ships unnoticed and surfaces as a support ticket about "weird results."
• Missing database capability. If a database-side unaccent function is expected and absent (common on managed PostgreSQL where CREATE EXTENSION is restricted), behaviour may degrade or error. Verify on a staging instance that mirrors production's managed-DB permissions, not on local Docker.
• Index bypass under load. The classic case: fine in staging, sequential scan in production.
• Non-Latin scripts. Diacritic folding is well-defined for Latin scripts; expectations for other input should be tested against real user data if the product is internationalised.
• Dependency abandonment. Low likelihood given current activity, but plan for it via the fork option above.

Ramp-up: A mid-level Laravel developer reaches productive use in a few hours; the package is small and the README (now with a stable banner, and with comments rewritten in plain English) is the primary reference. The non-obvious skills are on the database side — query plans and index strategy — so assign the spike to someone comfortable reading EXPLAIN output, or pair with a DBA. No training programme, no certification, no architectural review board required.

TPM recommendation: Adopt on a pilot basis. v2.0.4 itself requires no decision — it is documentation and CI only, with no code change and no compatibility risk. The decision that matters is the integration decision, and that should be gated on the spike answering the database-engine and indexing questions above.