Search Laravel Package

Technical Evaluation

Architecture fit. liberusoftware/search is a Laravel module that packages four concerns a TPM should treat as one capability: query authorization, filter composition, pagination, and a replaceable model-binding layer. Architecturally it sits above Eloquent and below your controllers — it is a read-path abstraction, not a full-text engine. The "replaceable model configuration" wording is the important signal: it implies an indirection contract (config-driven model map plus a filter/authorization interface) rather than a hard-coded repository. That is a good fit for a modular monolith that already follows Liberu conventions, and a reasonable fit for any Laravel app that wants to keep search behind a seam. It is a poor fit for teams that expect an out-of-the-box search backend (Scout/Meilisearch/Algolia); this package appears to govern how queries are built and authorized, not where they execute.

Integration feasibility. Mechanically low-friction: Composer install, service-provider auto-discovery, publishable config, then per-model registration. The real effort is organizational, not technical — you must define, for every searchable resource, (a) the filter allowlist, (b) the authorization policy or scope that constrains the base query, and (c) the pagination contract expected by clients. Budget roughly a day per resource for the first two resources and a few hours thereafter; the first one is where you learn the package's conventions.

Technical risk. Elevated, and dominated by signals unrelated to code quality:

• Zero ecosystem validation. 0 stars, 0 dependents, no downstream usage to inherit battle-testing from. Every edge case is your edge case.
• Bus-factor and continuity. Single-vendor package inside a broader Liberu module family; no evidence of a published security policy, changelog discipline, or LTS commitment.
• Security-critical surface. "Authorized search" means the package is in the enforcement path for data visibility. A defect or a mis-set default that widens a scope is a tenant-isolation or PII exposure incident, not a UI bug. Treat the default permissive vs restrictive posture as the single most important thing to verify in source.
• Data-quality flag. The listed last release date (2026-10-27) is in the future relative to normal review cadence. Confirm whether this is a metadata artifact, a mistagged version, or a genuinely pre-release artifact before pinning.

Key questions for the maintainer / source review.

1. Does the authorization layer constrain the SQL query (pre-filter) or filter hydrated models (post-filter)? Post-filtering breaks pagination counts and leaks existence via totals — disqualifying for multi-tenant use.
2. What is the default when no policy/scope is registered for a model: deny, allow, or throw?
3. Is pagination offset-based, cursor-based, or both? Can counts be disabled?
4. What is the exact Laravel/PHP support matrix, and is it enforced in CI?
5. How does the model map interact with global scopes, SoftDeletes, and third-party tenancy packages (e.g. stancl/tenancy)?
6. Is there a documented extension point for swapping the filter engine, and is that interface versioned/semver-stable?

Integration Approach

Stack fit. Target Laravel 10/11/12 on PHP 8.2+ with Eloquent as the data source. Position it as the policy and filter layer on the read path, and explicitly decide whether it fronts your OLTP database only or also fronts an external index. Recommended posture: use it for administrative/back-office filtered listing endpoints first (bounded blast radius, internal users), and keep customer-facing full-text search on your existing engine until the authorization semantics are proven.

Migration path — strangler, not rewrite.

1. Source audit spike (2–3 days). Read the authorization and pagination code paths; write a short internal ADR answering the key questions above. This gate is non-negotiable given the security surface.
2. Adapter seam. Define your own thin SearchCriteria / SearchResult interface in application code and implement it with this package. Nothing in your controllers imports the vendor namespace directly. This is cheap now and is the entire exit strategy later given MIT licensing.
3. Pilot one resource. Pick a low-sensitivity, read-heavy listing endpoint. Run it in shadow mode — execute both old and new query paths, diff result sets and total counts, log divergences — for one to two weeks.
4. Authorization conformance tests. Build a test matrix of {role × tenant × resource} asserting that denial happens at the query level, that counts match filtered sets, and that no cross-tenant identifiers appear.
5. Expand resource by resource, retiring the legacy path per endpoint only after its conformance suite is green.

Compatibility checks before pilot. Namespace and service-provider collisions with any existing search package; behavior under php artisan config:cache and route:cache (config-driven model maps frequently break here); interaction with your existing global scopes and any withoutGlobalScopes() calls already in the codebase; and whether its filter parsing conflicts with your request-validation layer.

Sequencing rationale. The adapter and the conformance suite are the load-bearing deliverables, not the package adoption itself. If the package fails the audit, the adapter work is not wasted — it becomes the interface for a ~200-line in-house implementation, which is a realistic fallback for a package of this scope.

Operational Impact

Maintenance. Assume you own it. With 0 stars and 0 dependents there is no implicit patch stream; your team is the de facto maintainer of any fork. Pin to an exact version, vendor-lock, and record the fork point in your dependency register. Budget a recurring, low-single-digit-percent-of-one-engineer cost for tracking upstream and re-basing — and accept that if upstream stalls, "track upstream" becomes "maintain patch set." MIT licensing makes forking legally trivial, which lowers the downside considerably but does not eliminate the labor.

Support. No community channel, no Stack Overflow corpus, no third-party tutorials. Ramp-up cost for a new engineer is therefore "read the source," not "read the docs." Mitigate with a one-page internal runbook: where the config lives, how to register a model, how to add a filter, how to add an authorization scope, and what the safe defaults are.

Scaling. Throughput is bounded by your database, not the package. Two specific pressure points:

• Index coverage. Dynamic filter composition will happily generate WHERE clauses on unindexed columns. Instrument slow-query logging on day one and treat every new filter as requiring an index review — this is the most likely production surprise.
• Count queries and offset pagination. Deep offset paging on large tables degrades non-linearly. If the package offers cursor pagination, prefer it for high-volume endpoints and disable total counts where the UI does not require them.

Failure modes, ranked by expected damage.

1. Authorization under-scoping → data exposure. Highest severity, lowest detectability. Detect with the conformance matrix in CI and with periodic cross-tenant canary queries in staging.
2. Post-filter authorization → pagination/count drift. Users see "1–10 of 400" but can only reach 37 results, or counts imply the existence of records they cannot read. Detect via shadow-diff on totals.
3. Missing index → query timeout under load. Detect via slow-query alerting; remediate by making index review a merge checklist item for any new filter.
4. Config-cache breakage → silent empty results. Model map unresolved after deploy yields zero rows rather than an error. Detect with a post-deploy synthetic search smoke test per resource.
5. Upstream abandonment → accumulating dependency debt. Detect by calendar, not telemetry: review upstream activity quarterly; escalate to fork-and-own if no commits for two release cycles.

Ramp-up. Low for any Laravel developer — a half-day to first working filtered, paginated, authorized endpoint — provided the source audit produced the runbook. The genuine learning curve is not Laravel knowledge but the package's conventions for model replacement and filter registration, which are undocumented at this maturity level.

Overall TPM verdict. Conditional go, scoped narrowly. The capability is well-aligned with a real gap (consistent authorization on filtered reads is usually duplicated ad hoc across controllers), and the license makes the exit cheap. But a composite score of ~20/100 with zero dependents means you are buying an interface design and a set of conventions, not a supported product. Approve a 2–3 day audit spike plus a single-resource pilot behind an internal adapter; do not approve org-wide adoption, and do not put customer-facing multi-tenant search behind it until the pre-filter authorization question is answered in writing.