Search Api Laravel Package

Product Decisions This Supports

• Build vs. buy for a search API surface. This package is a transport layer, not a search engine — it wraps authenticated, rate-limited HTTP endpoints around an underlying search implementation. The decision it informs is narrow: do we hand-roll our own /search controller, auth guard, and throttling rules, or adopt a pre-packaged module that already encodes those conventions?
• Time-to-market for exposing search to non-web clients. If a roadmap item requires search to be consumable by mobile apps, partners, internal services, or an admin console, this is a candidate to satisfy that requirement in days rather than a sprint.
• Service decomposition / modular monolith boundaries. Packages of this shape (a module-* namespace with an -api sibling) typically exist to carve a bounded context out of a monolith. Adopting it is a small, reversible step toward extracting Search as a standalone service later.
• Rate-limit and abuse policy as a product constraint. Because throttling is bundled rather than bespoke, it forces an explicit conversation about quota tiers, per-key limits, and what happens at the boundary — useful for pricing/packaging decisions on any metered or public-facing search feature.
• Scope discipline on relevance and ranking. Choosing this package signals that search quality is delegated elsewhere (Scout, Meilisearch, Elasticsearch, database full-text). That keeps relevance tuning off this team's roadmap and prevents the API layer from accumulating search-engine responsibilities it shouldn't own.

When to Consider This Package

Adopt it only when all of the following hold:

• You are already inside the Liberu module ecosystem, or you are deliberately standardizing on its conventions, so the naming, service provider wiring, and auth assumptions match your app.
• Your requirement is genuinely plumbing: authenticated access, per-client throttling, consistent JSON envelopes, and a stable route contract. Nothing more exotic.
• You accept that the package is a thin shell over an engine you still have to choose, configure, and operate.
• You can vendor, pin, and read the source — treat it as a starting template rather than a depended-upon library.

Look elsewhere (or write ~150 lines yourself with Sanctum + throttle middleware) when:

• Adoption signals are the deciding factor. 0 stars, 0 dependents, and a release date that appears auto-generated or placeholder indicate no meaningful production feedback loop. There is no community to catch regressions, no Stack Overflow corpus, no security disclosure history to lean on.
• You need faceting, typo tolerance, synonyms, relevance tuning, hybrid/semantic search, or index lifecycle management — those are engine concerns this package will not solve.
• You need observability and SLOs on search: latency percentiles, query analytics, cache hit rates, per-tenant cost attribution.
• You require contract versioning, OpenAPI specs, SDK generation, or pagination/cursor guarantees across multiple consumer teams.
• Your security posture demands a maintained dependency with a CVE process; a single-maintainer, zero-adoption module is a supply-chain question you must answer consciously.
• You need multi-tenancy isolation enforced at the search layer — verify this explicitly before assuming it exists.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed Laravel module that exposes your search capability over authenticated, rate-limited HTTP endpoints. It is cheap to try and cheap to remove. The honest caveat is maturity: effectively zero external adoption and no dependents means we are the first real user, so we should treat it as a reference implementation we own a fork of, not a vendor dependency. Recommendation: a one-to-two day spike, budgeted as a build-vs-buy evaluation — the realistic outcome is either fast validation of our API contract or a same-sized in-house implementation with full control.

To engineering: The package's value is concentrated in conventions — auth wiring, throttle configuration, and route/response shape — which overlaps heavily with what Laravel gives us natively via Sanctum and the throttle middleware. Before committing, confirm (a) which search backend it assumes and how that's injected, (b) whether tenancy and authorization are enforced per-request or assumed, (c) test coverage and how errors/timeouts from the backend surface to clients, and (d) whether the release cadence is automated. If any of those is unclear, fork it, keep the route contract, and replace the internals.

Positioning summary: Low-cost, low-risk-to-try, low-support — a useful skeleton for a search API, not a strategic dependency. Value it for the decisions it forces (quota policy, auth model, backend ownership), and hedge it behind an internal interface so swapping it out later is a non-event.