Criteria Laravel Package

Product Decisions This Supports

• Build vs. buy for query/filtering infrastructure. This package gives you the Criteria (Specification) pattern out of the box — composable, reusable, domain-level query objects that sit between your application services and your repositories. That's a well-understood pattern you can hand-roll in roughly 1–2 engineer-days; this package is best treated as a reference implementation or shortcut, not a strategic dependency.
• Architecture direction: domain/persistence separation. Adopting it encodes a decision that business rules about "which records qualify" should live outside Eloquent models. That matters if you're moving toward hexagonal/clean architecture, porting between ORMs, or planning to expose the same filters across multiple data sources (Elastic, read replicas, external APIs).
• Roadmap enablers: admin filter panels, saved searches, complex API query params. Criteria objects are the natural unit for a "filter builder" UI, reusable saved-search definitions, and consistent filtering across list endpoints — one definition, many consumers.
• DRY decisions across modules. If several modules (Reports, Billing, Admin, Customer Portal) each re-implement "active subscriptions in region X with past-due invoices," a shared criteria library replaces N divergent queries with one tested, named concept.
• Test strategy. Criteria are trivially unit-testable in isolation (no DB), so this supports a decision to shift filter-logic coverage from slow integration tests to fast unit tests.
• Not a decision-driver: this does not meaningfully affect scaling, performance, or deployment. It's an internal code-organization choice.

When to Consider This Package

Adopt (or copy) when:

• You have 3+ list/search endpoints whose filtering logic is duplicated or drifting, and a real maintenance cost is demonstrable.
• You're deliberately introducing a domain layer — Criteria is a poor fit if your app is idiomatic Laravel with Eloquent local scopes and nothing else.
• You need the same criteria reused across multiple query backends (e.g., Eloquent for writes/reads, a search index for listing).
• You want a named, serializable representation of a filter for saved views, alerting rules, or permissions-scoped queries.
• Your team already knows the pattern and just wants a small, MIT-licensed implementation to avoid bikeshedding.

Look elsewhere — or write 100 lines yourself — when:

• Vendor and adoption risk is disqualifying. 5 stars, 0 dependents, and a single-package SDK lineage mean no community pressure-testing, no Stack Overflow corpus, and no second maintainer. For a critical path, fork it into your codebase under your own ownership.
• You only need request-parameter filtering. spatie/laravel-query-builder is purpose-built for that, vastly more adopted, and integrates with Laravel's request/validation idioms.
• You're on Doctrine. Doctrine\ORM\Criteria is built in and better supported; don't layer a second abstraction over it.
• Your team is small and Eloquent-fluent. Local scopes plus a query-object convention cover 80% of the benefit at zero dependency cost. Introducing a criteria vocabulary is a tax paid in onboarding and code review.
• You need a compatibility guarantee. No published support policy, no versioning signal beyond a 2026 release date, and an API surface that tracks an upstream SDK. Pin it or vendor it, never float it.

Given the low opportunity score, the realistic recommendation is: evaluate as a design reference, not a dependency. Read the source, adopt the interface shape, own the code.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, free, open-source PHP library that organizes "how we filter and search data" into reusable, named, testable pieces instead of copy-pasted database queries scattered across the codebase. It costs nothing to license and is quick to adopt, but it is a single-maintainer project with essentially no user base — so we would treat it as a pattern to adopt, not a vendor to depend on. Expected value is lower defect rates and faster delivery of filtering/search features; expected cost is roughly a week of engineering to introduce and migrate existing endpoints. Recommend a scoped pilot on one module, with the code vendored under our ownership.

For engineering leadership:

• What it does: implements the Criteria/Specification pattern — composable query objects that decouple business filtering rules from Eloquent/Doctrine repositories.
• Why we care: filter logic is currently duplicated across list endpoints and is only covered by slow, database-bound tests. Criteria make it unit-testable and reusable across endpoints and data sources.
• Risk: 5 GitHub stars, zero dependent packages, single maintainer, unversioned support posture, and an API that follows an upstream SDK. Treat upstream as read-only inspiration; fork into app/Domain/Criteria (MIT permits this) and add our own tests.
• Alternatives considered: Eloquent local scopes (zero cost, weaker composition and no cross-backend reuse); spatie/laravel-query-builder (better for request-param filtering, not for domain-level reuse); Doctrine Criteria (built-in, only relevant if we move off Eloquent).
• Ask: two days of spike on the highest-duplication module, measured against query-test runtime and lines of duplicated filter code. Decision point: if criteria count stays under ~10 and reuse is under 2x, keep local scopes and stop.