Laravel Searchable Laravel Package

Technical Evaluation

What this release is: maize-tech/laravel-searchable 4.2.0 is a minor release whose only substantive change is declared compatibility with Laravel 13. The remaining three items are Dependabot bumps to CI-only GitHub Actions (git-auto-commit-action, laravel-pint-action, fetch-metadata) and carry no runtime footprint. There are no breaking changes, deprecations, or new search capabilities.

Architecture fit: The package provides a Searchable trait that lets Eloquent models declare searchable columns and relationships, exposing a Model::search($term) entry point that returns a standard query builder. This is an in-process, database-native alternative to Laravel Scout — no external engine (Meilisearch, Algolia, Typesense), no index synchronization, no queue workers, no additional infrastructure. Fit is strong for internal admin panels, back-office CRUD, MVPs, and low-to-moderate data volumes where "good enough" substring matching is acceptable. Fit is poor where relevance ranking, typo tolerance, faceting, or sub-100ms response over millions of rows is a product requirement.

Integration feasibility: Low effort. Composer install, add the trait, declare $searchable columns/relations, render a search box. No schema changes, no service provider configuration beyond optional publishing, no data backfill. A single engineer can typically ship a first integration in under a day. The Laravel 13 support in this release is the gating item for teams on the newest major.

Technical risk:

• Query strategy risk (highest): Search is implemented as LIKE '%term%' predicates. A leading wildcard defeats B-tree indexes, so every search is effectively a sequential scan. This is invisible in staging with 50k rows and becomes a production incident at 5M+.
• No relevance model: Results are ordered by whatever the caller specifies. There is no scoring, boosting, or prefix weighting. If the product spec says "best match first," this package cannot deliver it without custom work.
• Relation search cost: Searching across relationships generates correlated subqueries or joins; deep or multi-relation searches compound quickly and can emit duplicate parent rows requiring distinct.
• Collation sensitivity: Case- and accent-insensitivity are delegated to the database collation rather than handled in PHP, so behaviour differs between MySQL, PostgreSQL, and SQLite — a real problem given Laravel teams routinely use SQLite in tests and MySQL/Postgres in production.
• Wildcard injection by users: Literal % and _ in user input are interpreted as SQL wildcards unless escaped, producing unexpectedly broad result sets.
• Maintainer concentration: Change volume is dominated by Dependabot; this is a small, agency-backed package. Treat bus factor as a genuine consideration.

Key questions for the team:

1. What is the expected row count and query-per-second rate on the searchable tables at 12 and 24 months?
2. Is relevance ranking, typo tolerance, or faceting anywhere on the product roadmap? If yes, Scout + Meilisearch is the cheaper long-term bet.
3. Which database(s) run in production vs. test, and has accent/case behaviour been validated on the production engine?
4. Does the composer constraint in 4.2.0 retain support for our current Laravel version, or does Laravel 13 support come at the cost of an older major?
5. Are there multi-tenant scoping requirements that must be applied to every search query, and does the trait compose cleanly with a global scope?
6. What is the acceptable p95 latency for search, and has it been tested against realistically sized data?

Integration Approach

Stack fit: Native Laravel/PHP, no new runtime dependency, no infrastructure. It fits any Laravel 9–13 application using Eloquent. It is deliberately engine-agnostic, which is both its selling point and its performance ceiling. If the stack already includes Scout, do not add this package — running two search abstractions on the same models is a maintenance trap.

Migration path: Greenfield adoption is trivial: composer require maize-tech/laravel-searchable:^4.2, add the trait, declare searchable fields, done. Migrating away later is the asymmetry to flag — the trait is easy to remove, but any UI or API contract built on "substring match, no ranking" will need rework when moving to a real engine. Adopt it with an explicit understanding that it is a v1 search solution. Migrating from hand-rolled LIKE queries or where('name','like',...) scattered across controllers is a net positive and a natural consolidation point.

Compatibility: 4.2.0 explicitly declares Laravel 13 support, resolving the primary blocker for teams upgrading. Confirm the composer illuminate/* constraint range before assuming a single 4.2.x line covers both your current and target Laravel majors. PHP version support should be verified against your runtime. The CI action bumps have zero application impact and should not factor into the decision. Verify the package's test matrix actually exercises Laravel 13 rather than only widening the constraint — a declared-but-untested major is a common and painful failure mode.

Sequencing:

1. Pin ^4.2 if and only if you are on or moving to Laravel 13; otherwise ^4.1 is functionally identical and can be deferred to your next routine dependency sweep.
2. Spike on a non-critical internal surface (admin list view) first — never on customer-facing search.
3. Validate against a production-sized anonymized dataset before committing to the pattern; measure p95 latency and EXPLAIN the generated query.
4. Add explicit escaping of % and _ in any user-supplied term before it reaches the builder.
5. Roll out to remaining models only after the spike's latency numbers are accepted.
6. Document the exit criteria (row count or latency threshold) at which the team commits to migrating to Scout + an external engine.

Operational Impact

Maintenance: Near-zero steady state. No index to rebuild, no sync jobs, no external service to keep alive, no schema migrations introduced by the package. Upgrades are the only recurring task, and this release is a textbook example of a low-risk minor bump — one compatibility change plus CI housekeeping. Budget roughly an hour per release cycle to review the changelog and run the suite.

Support: Community-only via GitHub issues from a small agency maintainer. No SLA, no commercial backing, no security disclosure process documented. Acceptable for internal tooling; for a customer-facing, revenue-affecting surface this should be recorded as an accepted risk with an internal owner assigned. Track the release cadence — if Laravel 14 ships and support lags by more than a quarter, that is your signal to plan the exit.

Scaling: This is the dominant operational concern and it is not addressed by 4.2.0. Performance degrades roughly linearly with table size because of the leading-wildcard LIKE. Mitigations available without leaving the package: constrain searchable columns to short, indexed text; require a minimum term length; enforce a tenant or date filter before the search predicate so the scan is bounded; cap result pagination; consider a generated/derived indexed column for prefix-only matching where the UX permits. None of these restore true full-text performance. Establish a concrete threshold now — e.g. "if any searchable table exceeds 2M rows or p95 exceeds 500ms, migrate" — and put it in the backlog rather than discovering it under load.

Failure modes to monitor:

• Silent latency creep on search endpoints as tables grow — instrument p95 per search endpoint from day one, not just error rate.
• Full-table scans saturating the primary database under concurrent search load; watch for search queries dominating slow-query logs.
• Duplicate rows from relation searches where distinct was not applied.
• Overly broad matches when users type % or _.
• Divergent behaviour between test (SQLite) and production (MySQL/Postgres) on case and accent handling — a class of bug that passes CI and fails in front of users.
• Cross-tenant leakage if the search builder is invoked without the tenant global scope applied; validate explicitly.

Ramp-up: Very low. A Laravel-comfortable engineer is productive in under an hour; the mental model is "a trait that adds a scoped query builder." The knowledge that must be transferred deliberately is not how to use it but when it stops working — the performance ceiling and the collation caveats are not obvious from the README and will otherwise be rediscovered during an incident. Capture both in the integration ADR.