Search Laravel Package

Product Decisions This Supports

• Build vs. buy for search and filtering. rollerworks/search is a search abstraction layer, not a search engine. It lets a team define search conditions, fields, value normalization, sorting, and subscriptions once, then execute them against a backend (primarily Doctrine DBAL/SQL). That directly informs the recurring PM question: do we hand-roll filtering logic, adopt an abstraction, or buy a managed search service? This package supports the "adopt an abstraction and defer the engine decision" path.
• Roadmap sequencing for filtering features. Because conditions, fields, and value formatting are modeled explicitly, adding new filter types, sort options, or input-normalization rules becomes an incremental product decision rather than a rewrite. This is useful when the roadmap shows a progression from "basic admin filters" to "faceted catalog search" to "multi-backend search."
• Backend-agnostic search as a hedge. If the roadmap includes a possible migration from SQL to Elasticsearch/OpenSearch/Meilisearch, an abstraction layer is a risk-reduction decision. It keeps product-level search semantics stable while the storage layer changes underneath.
• Use cases it fits. Internal admin/back-office search and list filtering, catalog and inventory filtering with structured criteria, reporting-style query builders, and multi-tenant products where different tenants or deployments may run on different data stores.
• Use cases it does not decide for you. Relevance ranking, typo tolerance, fuzzy matching, and large-scale full-text search are engine concerns. This package will not substitute for a dedicated search engine in those decisions.
• Laravel-specific caveat that shapes the decision. The package is Doctrine DBAL-oriented rather than Eloquent-native. Adopting it in a Laravel codebase implies an integration layer and a mapping strategy between Eloquent models and search definitions. That is a real cost line in the build-vs-buy comparison.

When to Consider This Package

Consider it when:

• You need structured, criteria-based search and filtering (not relevance-ranked full-text search) and want the query-building logic decoupled from the storage layer.
• You expect the search backend to change or must support more than one, and you want a stable internal contract for search definitions.
• Your filtering logic has outgrown ad-hoc query-builder calls and Eloquent scopes, and consistency of value formatting, sorting, and condition composition is becoming a maintenance problem.
• You are comfortable owning an integration layer, and you value a small, MIT-licensed, single-purpose dependency over a heavier framework or a paid SaaS.
• You want search logic to be unit-testable independently of the database.

Look elsewhere when:

• You need relevance ranking, fuzzy matching, faceting UX, or high-volume full-text search — use a dedicated engine (Meilisearch, OpenSearch, Typesense, Algolia) and treat this package as, at best, a criteria layer in front of it.
• Your needs are simple WHERE/ORDER BY clauses on a handful of models — native Eloquent scopes are cheaper to build, cheaper to staff, and easier to hand over.
• Bus factor and community size matter to your risk profile. ~110 GitHub stars and a single-maintainer-style project mean limited ecosystem support, few Stack Overflow answers, and no vendor SLA. Budget for reading the source and pinning versions.
• You require vendor support, security SLAs, or long-term commercial backing.
• Your team is Laravel-native and Doctrine-averse; the abstraction's value may not justify the paradigm mismatch.
• You need official, current documentation and a large hiring pool of engineers who already know the tool.

A pragmatic middle path: adopt it behind your own thin SearchService interface so the package is swappable, and pin the version. That preserves the architectural benefit while containing the maintenance risk.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed PHP library that gives us a clean, engine-independent way to express search and filtering. The commercial case is option value and cost avoidance: we can ship filtering features now on our existing database infrastructure, and later move to a managed or open-source search engine without rewriting product-level search behavior. License cost is zero; the investment is a modest integration effort and ongoing ownership. The main risk is that it is a small community project — we mitigate that by wrapping it behind our own interface, pinning versions, and treating it as an internal implementation detail rather than a platform commitment.

For engineering: It separates what we search for (conditions, fields, sorting, value normalization) from how it is executed, which makes search logic testable and portable. The trade-off is that it is Doctrine DBAL-oriented, so Laravel integration needs a deliberate mapping layer, and the project is small enough that we should expect to read the source and own our usage patterns. Recommended stance: adopt behind an internal abstraction, restrict it to structured filtering, and keep full-text relevance on a dedicated engine.