Data Grid Laravel Package

Product Decisions This Supports

• API contract surface: spiral/data-grid makes "which fields can a customer filter and sort by?" an explicit, versioned artifact (a specification class) rather than an emergent property of whatever the controller happens to read from the query string. That is a product decision, not just a technical one — it defines what slicing capability we sell/enable.
• Build vs. buy on collection endpoints: the real alternative is not another library, it's ~150–400 lines of hand-rolled $request->query() parsing repeated per endpoint, or a full admin-panel generator. This package sits in the middle: a small, MIT-licensed specification builder you wire to your own query layer.
• Roadmap: self-serve data access. If the roadmap includes "let customers/admins slice their own data" (B2B admin tables, exports, saved views, reporting filters), this is the enabling primitive. It also leaves room for later transports (saved filter JSON, API params, embedded grid configs) because specs are decoupled from the request.
• Consistency across N list screens: standardizes sorting/filtering/pagination semantics (allowed operators, defaults, limits) so ten admin screens don't behave ten different ways. Reduces support tickets of the "why can't I sort by X here?" variety.
• Security/abuse posture: whitelisting filterable fields becomes structural instead of a code-review checklist — a measurable reduction in "customer filtered by an unindexed column and took down the DB" risk.
• Do not use it as the decision driver for: search relevance, faceted navigation, or admin UI generation. Those are separate buy decisions (Scout/Meilisearch/Typesense; Filament/Nova) and this package does not replace them.

When to Consider This Package

Adopt when:

• You have 5+ collection endpoints with overlapping filter/sort/paginate needs, or a clear roadmap to them.
• The team is comfortable with the specification pattern / layered PHP and wants filters as typed, unit-testable classes instead of controller-level query-string spaghetti.
• You need a framework-agnostic spec you can feed from multiple transports later (HTTP query, saved views, internal service calls).
• You want strict allow-listing of sortable/filterable fields as a first-class concept.
• You accept owning a thin integration layer yourself — the core is a spec builder; Laravel/Eloquent wiring comes via a companion bridge and will need validation against your query builder usage.

Look elsewhere when:

• 1–3 endpoints. The abstraction overhead exceeds the duplication it removes. Eloquent scopes or spatie/laravel-query-builder are faster to ship and far more idiomatic for a Laravel team.
• You need an admin UI, not a query contract → Filament, Nova, Backpack.
• You need relevance ranking, faceting, fuzzy/full-text, typo tolerance → Scout + Meilisearch/Typesense, or Elasticsearch. A spec builder will not get you there.
• Pagination is the only requirement → Laravel's paginator, full stop.
• Adoption risk is unacceptable. 54 stars and 0 dependents is a real signal: no StackOverflow corpus, few blog posts, few battle-tested edge cases, and you become the maintainer of last resort on upgrades. The Spiral team ships regularly (latest release July 2025, MIT), so it isn't abandoned — but it is niche.
• Team velocity depends on copy-pasteable examples. Documentation depth is the weak point; budget for a spike.
• Performance is the primary constraint. It builds specifications, not optimized SQL. Query plans and index coverage remain your problem.

Practical gate before committing: a one-sprint spike on two real endpoints, measuring (a) lines of code removed, (b) generated SQL sanity, (c) whether the Laravel bridge covers your query patterns, and (d) whether a junior engineer can add a new filter without reading the source.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a small, free (MIT) PHP library that turns filtering, sorting, and pagination into a defined, reviewable product contract instead of ad-hoc code scattered across endpoints. The business value is speed and safety: every new "let customers filter their data" request becomes a ~20-line spec change rather than a custom build, and the set of things customers are allowed to filter by becomes explicit and auditable. Cost is negligible; the risk is that it's a niche library with a small community, so I recommend a bounded two-week pilot on 2–3 endpoints behind our own internal interface, which we can swap out for a hand-rolled version in about a day if it disappoints.

For engineering leads: The core package is ORM-agnostic — you define immutable grid specifications, one mapper parses the request into a spec, and readers translate specs into your data source. That separation is genuinely useful: it gives us thin controllers, testable filter logic, and a single place to enforce allow-lists. The trade-offs are an extra abstraction layer, a bridge package we'll need to validate against our query-builder patterns, and thin documentation. Mitigation: wrap it behind our own GridService contract so the library is an implementation detail, not a dependency smeared across controllers. If the spike shows friction, we drop it and keep the interface.

Positioning vs. alternatives: not a replacement for Filament/Nova (UI) or Scout/Meilisearch (search relevance) — it's the layer between "HTTP request" and "database query." Frame it as infrastructure, and let the pilot, not the pitch, make the call.