Laravel Repository Laravel Package

Product Decisions This Supports

• Search correctness is a product feature, not an implementation detail. 1.0.5 fixes a query-grouping defect in FuzzySearch: previously, chaining FuzzySearch (which emits OR between its fields) with AttributeSearch (which emits AND) produced unparenthesised SQL, so the AND filter bound only to the last OR branch. In practice a name-match could bypass the city filter entirely, and a pinyin match could ignore it too. Post-1.0.5 the fuzzy group is wrapped, so (name LIKE … OR pinyin LIKE …) AND city = …. This directly changes result set composition for any multi-field search plus filter screen — expect result counts to drop and previously "impossible" rows to disappear.
• Multi-field search + faceted filtering can be shipped without a search cluster. The criteria-composition pattern (pushCriteria) lets the team layer fuzzy keyword matching on translatable fields (name, pinyin) with exact attribute filters (city), building a usable Chinese-market search/filter experience on plain MySQL. This is a credible v1 for catalogue, user directory, CRM, or admin listing screens, deferring Elasticsearch/Meilisearch spend.
• Build-vs-buy: staying on the repository + criteria pattern (vs. hand-written query scopes or jumping to Laravel Scout) keeps search logic declarative and testable per-criterion. This release removes the main reason to hand-roll grouped where closures, so "build custom" loses an argument.
• Roadmap input: now that composition is correct, prioritise (a) verifying filter/result parity across existing screens, (b) query-cost work — leading-wildcard LIKE "%term%" cannot use an index and will table-scan; introduce prefix search, generated pinyin columns with indexes, or a search engine once row counts or latency budgets bite, (c) relevance/ranking and typo tolerance, both out of scope for LIKE.

When to Consider This Package

• Adopt when: you're on Laravel + MySQL/Postgres, data volume is modest (roughly low-hundreds-of-thousands of rows per searchable table), you need keyword matching across multiple columns plus exact filters, and especially when you need pinyin/transliteration search for Chinese-language users — a niche most search packages don't cover.
• Adopt when: you want search/filter predicates expressed as reusable, individually testable criteria objects composed at the call site rather than as growing conditional blocks in controllers or repositories.
• Look elsewhere when: you need relevance ranking, highlighting, typo tolerance, synonyms, or sub-100ms response over millions of rows — use Laravel Scout with Meilisearch/Typesense/Elasticsearch/OpenSearch. LIKE '%term%' semantics will not get you there.
• Treat with caution when: upgrading existing installations. Despite the patch version, 1.0.5 is a behaviour change — audit every screen combining FuzzySearch with AttributeSearch (or any AND-emitting criterion), and look for local workarounds that added manual grouping or reordered criteria to compensate for the bug; those will now double-group or filter incorrectly. Run regression comparisons on result counts before rollout, and pin the version explicitly rather than floating.

How to Pitch It (Stakeholders)

To executives: We depend on a small Laravel search component to power keyword-plus-filter screens (search by name or pinyin, filter by city) without paying for a search cluster. Version 1.0.5 fixes a defect where our city filter was silently ignored for some keyword matches — meaning users could see results outside their selected filter. The fix is small and contained, but it changes what users see: result counts on affected screens will drop to the correct set. Recommendation: ship it, run a short QA pass on search screens, and flag that our current keyword search will need investment (indexing or a search engine) as data grows, because it scans the whole table per query.

To engineering: Upgrade to 1.0.5 and verify grouped SQL for any criteria chain mixing FuzzySearch with AttributeSearch. Remove any local query-grouping workarounds added to compensate for the old behaviour. Add regression tests asserting the emitted WHERE clause shape for chained criteria — this class of bug is invisible to happy-path tests. Separately, open a ticket on leading-wildcard LIKE cost and index strategy for name/pinyin.