Strsim Laravel Package

Product Decisions This Supports

• Feature scoping for fuzzy matching: Supports decisions about adding typo tolerance, “did you mean” suggestions, fuzzy lookup in admin tools, and approximate name/address matching without building algorithm primitives from scratch.
• Data quality and deduplication roadmap: Enables prototypes for contact-import deduplication, CRM record matching, near-duplicate listing detection, support-ticket duplicate detection, and catalog cleanup. v1.2.0’s rolling-row rewrite (Levenshtein on 2,000-char strings: ~8,950 ms / 70 MB → ~163 ms / 0.3 MB) widens this from “small batches only” to larger batches, longer fields, and longer strings — product descriptions, full addresses, and free-text ticket bodies are now tractable without a queue-and-shard design.
• Build vs. buy/adopt: The package is a small MIT-licensed implementation of Levenshtein, Damerau-Levenshtein, Jaro-Winkler, Hamming, cosine, and related algorithms. Adopting it may be cheaper than implementing and testing those algorithms in-house, but PHP already provides levenshtein(), similar_text(), soundex(), and metaphone(). The package is most justified when the product specifically needs Jaro-Winkler, Damerau-Levenshtein, or a consistent algorithm interface — and now more defensibly when it needs bounded-memory scoring over longer strings, which the built-ins do not give you.
• Architecture decision: Treat it as an algorithm library, not a search platform. Product code should call an internal similarity service/wrapper so we can swap implementations, add normalization, apply thresholds, and benchmark quality.
• Prioritization: A time-boxed spike remains low effort and low integration risk. It is not a strategic platform commitment and should sit behind a feature flag or internal-only workflow until quality metrics are proven. The performance work removes the most common “we’d have to rewrite this ourselves at scale” objection, so the spike can now be scoped against realistic data volumes rather than toy inputs.
• Vector-similarity adjacency (new): Cosine support means the library can serve small in-process vector comparisons (tag/category vectors, lightweight embeddings from an external model). Scope this narrowly — v1.2.0 compares mismatched vector keys by position, so any keyed-vector use needs our own key alignment before calling in.
• Use-case fit: Good for small-to-medium batch matching, admin-side fuzzy search, import cleanup, deterministic scoring rules, and longer-string comparison at bounded cost. Still a poor fit for large-scale real-time search, ML-based semantic matching, or compliance-grade identity resolution.

When to Consider This Package

Consider it when:

• The product needs Jaro-Winkler, Damerau-Levenshtein, Hamming, or cosine similarity behind one PHP API, and the team does not want to maintain those implementations.
• Workloads are batch, offline, low-QPS, or admin-facing. v1.2.0 materially raises the ceiling here: constant-memory DP means record counts and field lengths are now limited by CPU budget rather than memory blowups, so mid-size backfills and on-demand admin comparisons are reasonable.
• Strings are long enough that memory/allocation was the blocker (addresses, product titles plus descriptions, ticket bodies). This is the clearest new justification versus PHP built-ins.
• The team can own input normalization — lowercasing, trimming, transliteration, tokenization, threshold tuning — rather than expecting the package to solve matching end-to-end. ext-mbstring is now a declared requirement, which helps, but declaration is not the same as validated multilingual behavior.
• The runtime baseline is PHP 8.2+. This is now a hard floor; it will block adoption on older LTS stacks and should be confirmed before the spike is scheduled.
• A small MIT dependency is acceptable and the team will pin versions, wrap usage, and add its own tests/benchmarks.
• The alternative is custom algorithm code with no tests, or a heavier external search service that is disproportionate to the use case.

Look elsewhere when:

• The requirement is large-scale typo-tolerant search or autocomplete. Use Elasticsearch/OpenSearch, Meilisearch, Typesense, Algolia, or PostgreSQL pg_trgm instead. The v1.2.0 speedups do not change this — they improve per-comparison cost, not indexing, candidate retrieval, or query latency at scale.
• Unicode/multilingual correctness is critical. The mbstring declaration and invalid-UTF-8 rejection in Hamming are improvements, but they are guardrails, not a multilingual correctness guarantee; validate transliteration, normalization, and per-language thresholds against real data.
• The use case is compliance-grade identity resolution, KYC, sanctions screening, or fraud decisioning. Use specialized vendors, human review, and auditable scoring.
• The team needs phonetic matching, token-based matching, or learned semantic similarity. Cosine on raw vectors is not a substitute for an embedding pipeline.
• Behavioral changes are unacceptable without a migration pass. v1.2.0 changes cosine semantics for mismatched keys and makes Hamming reject invalid UTF-8 — both can silently shift scores or surface exceptions where the previous version returned a value.
• The organization has a low tolerance for single-maintainer, low-adoption dependencies. Adoption remains low (30 stars, 0 dependents); CI across PHP 8.2–8.5, phpunit.xml.dist, and a checked-in LICENSE are modest maturity signals, not a support commitment.
• Only Levenshtein or similar_text is needed on short strings. PHP built-ins are sufficient and avoid a new dependency.
• The organization requires vendor support, SLAs, or a mature security/maintenance program.

How to Pitch It (Stakeholders)

Executive summary: edgaras/strsim is a small, MIT-licensed PHP library for string similarity and distance algorithms. It can help us prototype fuzzy matching, deduplication, and data-quality features at low cost. Release v1.2.0 is a meaningful engineering upgrade — a rolling-row rewrite cut a representative Levenshtein comparison from roughly 9 seconds and 70 MB to about 0.16 seconds and 0.3 MB — which turns it from a toy-scale utility into something usable on realistic record volumes. It is still an algorithm primitive, not a search engine or identity-resolution platform.

Recommendation: Approve a time-boxed, feature-flagged pilot if a concrete roadmap item needs Jaro-Winkler, Damerau-Levenshtein, or multiple similarity algorithms — and now also if the blocker was memory or string length rather than raw comparison count. Confirm the PHP 8.2+ runtime floor first. Do not make it a platform-level commitment.

For engineering: Integration cost is low. Wrap the library behind an internal similarity service, add normalization and threshold configuration, benchmark against real data, pin the version, and include fallback behavior. Two v1.2.0 changes need explicit handling: cosine now compares mismatched vector keys by position (align keys in our wrapper), and Hamming rejects invalid UTF-8 (sanitize or catch upstream). Re-run any existing benchmarks — prior performance assumptions are now stale in both directions.

Risks to state plainly: Low adoption and single-maintainer risk persist; Unicode/multilingual behavior is better guarded but still unverified for our locales; there is no vendor support; and the 8.2+ floor narrows where this can be deployed. These are manageable for a bounded internal use case but not for compliance-critical matching.

Success measures: duplicate-match precision/recall, false-positive rate, reduction in manual cleanup, search zero-result rate, and conversion or support-ticket deflection where fuzzy matching is user-facing. Add batch wall-clock time and peak memory as engineering-health measures — v1.2.0 makes these trackable and they are the clearest evidence the upgrade was worth taking. If the pilot does not move the product metrics, fall back to built-ins or a search engine.