Bruno Laravel Package

Product Decisions This Supports

• Build vs. buy for the read API contract. Bruno is a thin, MIT-licensed convention layer over Eloquent that turns query-string parameters into sorting, filtering, eager loading, and pagination. It mostly replaces "we wrote 200–400 lines of per-controller query parsing" — so the real decision is adopt a house convention now vs. hand-roll it again vs. standardize on spatie/laravel-query-builder.
• Feature scoping. It makes "list endpoints support sort/filter/include/paginate" a one-sprint deliverable instead of a theme. That directly unblocks frontend data tables, admin consoles, mobile list screens, and partner/integration consumers who need a predictable, documented query grammar.
• Roadmap sequencing. Because it standardizes the grammar early, later work (cursor pagination, field selection, saved-view filters) becomes an additive change rather than a breaking redesign of every endpoint. It also forces an early, useful conversation about which filters and includes are sanctioned, which is really an API-governance decision.
• Use cases it fits. Internal admin/back-office APIs, BFF services behind a SPA, and partner endpoints where users want ad-hoc sorting and filtering but you don't want to fund GraphQL.
• Decisions it does not settle. Authorization scoping (you still own per-query policies), multi-tenant isolation, caching, API versioning, and search relevance stay on your plate. Treat Bruno as plumbing, not as an API strategy.

When to Consider This Package

Consider it when: you have a cluster of near-identical Eloquent list endpoints; your filters are simple column comparisons and your includes are Eloquent relationships; you want one documented query grammar shared by SPA, mobile, and partners; and you're comfortable owning the code if the maintainer disappears (the package is small enough to vendor or fork).

Look elsewhere when:

• You need nested/relationship filtering, validated filter operators, or search — spatie/laravel-query-builder has far more adoption, more operators, and healthier maintenance; it should be your default comparison.
• You need field selection, aliasing, or anything GraphQL-shaped.
• Your API is public/versioned and needs explicit, per-field authorization and request validation — that's better served by API Resources plus explicit requests than by a convention-driven base controller.
• Cursor pagination, heavy pagination customization, or tenant scoping must be baked in.
• Bus factor is a gating criterion: 163 stars, zero dependents, and a single maintainer is the actual risk here, not the MIT license.

Adoption guardrails either way: pin the version, and wrap it behind your own ApiController so a swap is a one-file change.

How to Pitch It (Stakeholders)

For executives (30 seconds): "A free, MIT-licensed Laravel component that gives every list endpoint consistent sorting, filtering, eager loading, and pagination straight from the URL — no per-endpoint code. It removes roughly one to three engineer-weeks of boilerplate per API surface and lets us ship filterable APIs in days. There's no service to run and no license cost; the risk is that it's a small single-maintainer project, so we'll pin the version and isolate it behind our own base class."

For engineering: small surface area, Laravel-native (Eloquent + the standard paginator), no runtime dependency, and an easy exit. Worst case we vendor a few hundred lines. We isolate it behind an internal base controller so migrating to spatie/laravel-query-builder later touches one file, not every feature. Known limits to accept up front: simple filter operators, Eloquent-relationship includes only, and no built-in per-field authorization.

Recommendation: pilot on one internal API, measure the boilerplate actually avoided, then either standardize or swap — with the wrapper in place from day one so the decision stays reversible.