Data Grid Laravel Package

Technical Evaluation

Architecture fit

• spiral/data-grid is a specification builder, not a UI grid and not a query builder. It gives you an immutable object graph — filters, sorters, paginators — plus a Driver contract that translates that specification onto a data source. The core is framework-agnostic and does not depend on Laravel, Spiral's container, or any HTTP layer, which is the main reason it is even worth evaluating for a Laravel stack.
• The pattern is a good fit for any application with many list/read endpoints: it centralises "which fields are sortable/filterable, how is input parsed, how is the query constrained" into one declarative place instead of scattering request()->get('sort') logic across controllers and repositories.
• It is not a fit if the team expects drop-in Laravel ergonomics (Blade components, Livewire, php artisan scaffolding). There is no Laravel-first equivalent of what spiral/filters or Spiral's grid bridge provides.
• Conceptual mismatch worth flagging: Laravel teams typically reach for spatie/laravel-query-builder or EloquentFilter for the same job. spiral/data-grid offers a stricter, more typed, more serialisable spec model, but at the cost of writing and owning the Eloquent glue yourself.

Integration feasibility

• Feasible but non-trivial. The expected path is: install the core package, write a custom driver implementing Spiral's driver interface against Illuminate\Database\Eloquent\Builder / the Query Builder, and adapt Laravel's Request into the grid's input object (the reference implementations assume PSR-7 request input).
• The driver is the entire integration risk. Expect ~200–500 lines covering: filter operator mapping (like, gt, in, between), sort whitelisting, pagination (offset/limit plus a separate count), and error handling for unknown field names. This is bounded, reviewable work — not a research project — but it is permanent in-house code.
• No official Laravel driver and 0 listed dependents means you cannot lean on community patterns, blog posts, or third-party bug reports when the glue misbehaves.
• Verify before committing: PHP version constraint vs. your runtime, whether the released version is compatible with your Laravel major (indirectly, via illuminate/* if any driver pulls it in), whether specifications are serialisable (useful for caching/hashing filter state), and how the package signals invalid input vs. throwing.

Technical risk

• Ecosystem risk (high): 54 stars, 0 dependents, single-vendor stewardship. This is a low-adoption package inside a niche framework's ecosystem. The score of ~4.1 with an opportunity signal of ~30.7 is consistent with "technically decent, strategically marginal."
• Maintenance risk (medium-high): releases are infrequent; if Spiral pivots its internal APIs, the Laravel-relevant core may drift without anyone filing the issue your team would have filed.
• Bus-factor risk (high): the driver you write becomes an undocumented internal dependency that only its author understands. This is the dominant cost, more than the package itself.
• Low technical risk in the code itself: MIT licence, small surface area, no runtime magic, no global state, no service-provider side effects to collide with Laravel's container. Reading the whole core is an afternoon.
• Security surface: filter/sort field names arrive from the client. The package gives structure but the driver must enforce a strict allowlist; a naive implementation is a SQL injection or information-disclosure vector via column names. Treat this as a mandatory review gate.

Key questions

1. Is there an existing, maintained Eloquent or Doctrine driver we can vendor/fork, or are we starting from the interface?
2. Does the core impose any PSR-7 / container assumptions that need shimming inside Laravel?
3. What is the package's release cadence over the last 24 months, and has the driver-facing interface changed across those releases?
4. Can specifications be serialised and rehydrated — i.e. can we hash a filter set for caching or persist saved views?
5. Does the maintainer respond to issues, and is there a stated support window?
6. What is the concrete alternative we are rejecting (spatie/laravel-query-builder), and what does this package buy us that it does not?

Integration Approach

Stack fit

• Composer-installable into any PHP 8.x / Laravel 10–12 application; the core's framework-agnosticism means no service provider conflicts, no config publishing, no facade aliasing.
• Best fit: applications with a large number of read endpoints over Eloquent models where filter/sort semantics must be consistent and auditable (admin panels, partner APIs, reporting surfaces).
• Poor fit: single-endpoint use cases, teams without appetite to own a driver, or teams already standardised on a query-builder package.

Migration path

• Do not retrofit existing endpoints. Introduce it on one new read endpoint, behind an application-level interface (GridQuery::for(Model::class, $spec)) so the package never leaks into controllers or domain code.
• That indirection is the real deliverable: if the package is abandoned, you swap the implementation behind your interface in one file rather than across the codebase.
• Keep the driver in a first-party package/module (app/Grid/ or an internal composer package) with its own tests, so it survives as an asset independent of the upstream dependency.

Compatibility

• Pin the upstream version exactly ("spiral/data-grid": "x.y.*") rather than using a caret constraint; with low release volume you gain little from float and lose reproducibility.
• Watch PHP minor-version support and any transitive psr/* constraints against the rest of the lockfile.
• Test the driver against your actual Laravel major in CI, since upstream will not.

Sequencing

1. Spike (2–3 days): read the core, prototype a minimal Eloquent driver for one model with equality + like filters, one sort, offset pagination. Decide go/no-go on the ergonomics.
2. Harden the driver (1–2 weeks): operator matrix, allowlists, nested/relation filters if needed, deterministic sort tie-breaking, explicit error semantics.
3. Pilot (1 sprint): one production endpoint, behind the internal interface, with contract tests and a load check on a realistically sized table.
4. Document and review: driver README, ADR recording why this over spatie/laravel-query-builder, and an exit plan.
5. Expand only if steps 1–4 held up; otherwise retire the spike — the sunk cost is a few days.

Operational Impact

Maintenance

• Recurring cost is modest but permanent: an internal driver to maintain, upstream version bumps to validate, and PHP/Laravel upgrade work that upstream will not do for you. Budget roughly a few days per year in steady state, plus a spike on each Laravel major.
• Recommend an explicit ADR and a "vendor risk" line in the dependency register; treat this as an in-house component with an upstream dependency, not as a normal composer package.

Support

• MIT with no SLA. Issue response is best-effort from a small team focused on Spiral. Assume you are on your own for the Laravel-side glue, and that upstream fixes for Laravel-specific problems will never arrive.
• Mitigation: fork rights are unambiguous under MIT; keep the fork path documented (which version, which patches) so a takeover is a day, not a quarter.

Scaling

• Specification construction is negligible in cost relative to the query. Performance is entirely determined by driver quality: correct index usage, avoiding COUNT(*) on large filtered sets, avoiding N+1 when filters touch relations, and stable keyset pagination if you exceed offset limits.
• At high request volume, spec-object allocation is noise; the real ceilings are the count query and any relation-based filtering. Cache total counts where the UI tolerates approximate pagination.

Failure modes

• Unknown/malicious field names in sort or filter → exceptions at best, injection at worst. Allowlist at the driver boundary.
• Unbounded filters (client sends 40 predicates) → pathological SQL. Cap predicate count and nesting depth.
• Type coercion mismatches (string "0" vs. boolean, date formats) → silently wrong result sets, which are harder to detect than errors.
• Pagination drift under concurrent writes with offset pagination — a known limitation, not a package defect, but it must be an explicit product decision on any endpoint where it matters.
• Upstream abandonment: if the package stops receiving releases, the pinned version keeps working until a PHP/Laravel upgrade forces the fork. That is a slow-burn, not an outage — acceptable if the interface indirection is in place.

Ramp-up

• One to two days for a senior PHP developer to read the core and understand the specification/driver split; the pattern is well-established and the codebase is small.
• The longer ramp is convention, not code: the team needs a written standard for which fields are filterable, how operators map, and how failures surface. Without that, every developer invents their own semantics and the centralisation benefit evaporates.
• Onboarding risk concentrates on the one person who wrote the driver — mitigate with tests as the specification and a mandatory second reviewer on any driver change.
• Verdict for a TPM: technically sound and cheap to try, strategically thin (54 stars, 0 dependents, niche ecosystem). Green-light only as a bounded spike behind an internal interface, with the explicit expectation that the driver — not the package — is the thing you are committing to maintain.