Laravel Request Scope Laravel Package

Product Decisions This Supports

• API contract design for list endpoints. Committing to query-parameter conventions (?sort=-created_at&filter[status]=active) is a product decision, not just a technical one: it becomes a public interface that clients, mobile apps, and integrations will depend on. This package is the vehicle for that decision.
• Build vs. buy for filtering/sorting. Every Laravel product eventually grows bespoke if ($request->has('status')) blocks in controllers. The real decision is whether to standardize on a declarative, whitelist-driven convention or keep hand-rolling per endpoint. This package represents the "standardize" option with a small, swappable dependency.
• Roadmap sequencing for data-heavy surfaces. Admin panels, internal tools, reporting screens, exports, and data tables all consume the same capability. Adopting a single convention lets you ship many such screens in parallel without each squad reinventing sorting semantics (nulls first/last, multi-column sort, stable tiebreakers).
• Feature scope for customer-facing list views. Saved views, segments, and shareable filtered URLs are only cheap if the query layer is URL-addressable and stateless. This package makes "save this filter" a near-free feature rather than a backend project.
• Security posture decision. A whitelist of sortable/filterable fields is the difference between a query-param API and an ORDER BY injection surface. Choosing this class of package is a decision to make that whitelist the default discipline rather than an afterthought.
• Explicit non-decision: it does not decide your query language. If the roadmap points toward GraphQL, OData, JSON:API sparse fieldsets, or a full-text search product, this is a stopgap, not a foundation.

When to Consider This Package

Adopt when:

• You have (or will have) three or more list endpoints that need consistent filter/sort behavior, and inconsistency across them is already causing support tickets or client bugs.
• Your team is Laravel/Eloquent-native and wants convention over a custom query DSL.
• You want filtering to be declarative and whitelisted — sortable/filterable fields defined next to the model or controller, reviewable in code review.
• You need it now: internal tools, back-office screens, or an MVP API where time-to-first-endpoint dominates.
• You value a thin abstraction with low exit cost — the payload is query-param parsing, so ripping it out later is a contained refactor.

Look elsewhere when:

• Adoption risk is unacceptable. Zero stars, zero dependents, and a score of 0 mean no community signal, no third-party battle-testing, and single-maintainer bus factor. For a customer-facing, long-lived API, treat this as unvetted code you are choosing to own — budget for reading the source, pinning the version, and possibly vendoring or forking.
• You need capabilities beyond filter/sort: relation includes with eager-load guarantees, sparse fieldsets, cursor pagination, aggregations, or full-text search. Mature alternatives in this space (e.g., spatie/laravel-query-builder) exist specifically because these are common next asks.
• The query string is a stable public contract. Once clients depend on filter[...] semantics, migrating to a richer or differently-shaped DSL is a breaking change with a deprecation cycle — decide the long-term shape before you ship.
• Your filtering needs are genuinely trivial (one or two endpoints, one or two fields). A package here is ceremony; a scoped query in the controller is honest.
• Your team has no appetite for owning third-party code with no upstream community.

Due-diligence checklist before adoption: last commit recency, test coverage, whether it supports your Laravel/PHP version matrix, whether sort/filter inputs are validated against a whitelist, and whether it plays nicely with pagination and query caching.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost standardization that lets us ship filterable and sortable data views — admin tools, reporting screens, customer list pages — faster and more consistently. The value is in velocity and uniformity, not novelty: it replaces repeated custom code with one reviewed convention. Because it's a thin layer over query-param parsing, the downside is bounded and reversing it later is a contained engineering task, not a re-architecture. The main caveat to flag is maturity: the package has essentially no community adoption, so I'd recommend a time-boxed spike and a code review before we standardize on it, and I'd avoid making it the foundation of a public API contract without that review.

To engineering: Adopt a declarative, whitelist-driven convention for sort/filter query parameters so we stop hand-rolling per-endpoint conditionals. Define allowed fields explicitly — this is the security boundary against ORDER BY injection — and keep the abstraction thin so it's replaceable if our needs grow toward relation includes, sparse fieldsets, or a proper query language. Read the source before merging; with no upstream community we are effectively the maintainers, so pin the version and add integration tests around the endpoints that depend on it. If we need more than filter-and-sort within the next two quarters, evaluate a more established alternative now rather than paying a migration later.