optimus/bruno
Bruno is a Laravel package by Optimus that provides a simple, fluent way to manage and organize your application's data, helping developers build cleaner, more maintainable Laravel projects with less boilerplate.
Architecture fit. Bruno is a base-controller package for Laravel: you extend (or fluently instantiate) BrunoController, declare a $resource model plus $filterable, $sortable, and $eagerLoad properties, and it translates query parameters into Eloquent query builder calls with pagination baked in. That is a legitimate REST-JSON pattern and it fits Laravel's controller/Eloquent idiom cleanly. The architectural cost is inheritance-based coupling — your API controllers become subclasses of a vendor class, which constrains any house base controller, cross-cutting middleware, and future portability. It is best suited to greenfield or self-contained API modules rather than a large monolith with an established controller hierarchy.
Integration feasibility. Composer-installable under optimus/bruno (originally esbenp/bruno), MIT licensed, and mechanically simple: no service provider complexity beyond standard registration, no schema changes, no queue or cache dependencies. The real integration work is (a) deciding whether controllers extend the vendor class or whether you wrap it in a local base class, and (b) reconciling its response envelope with your existing API contract (pagination shape, data/meta keys, transformer output). For an existing codebase, that reconciliation is the majority of the effort.
Technical risk. Moderate, driven more by ecosystem signals than by code quality. 163 stars and effectively zero tracked dependents is a thin footprint for a package whose job is to sit on the request path of every filtered endpoint, and the project's lineage (personal fork → optimus namespace, single-maintainer history) is a bus-factor concern. The last release (Jan 2025) indicates it is not abandoned, which is reassuring, but the community-standard answer to this problem today is spatie/laravel-query-builder, which has orders of magnitude more usage and maintenance depth. The opportunity score (25.2) reinforces that this is a niche fit rather than a widely-vetted default. There is also inherent risk in any query-parameter-driven filtering layer: it must whitelist columns, cap per_page, and guard include/eager-load lists, or it becomes a data-exposure and performance vector.
Key questions.
composer.json actually constrain, and is Laravel 11/12 supported?optimus fork, and what is the release cadence behind the Jan 2025 tag?league/fractal or other transitive dependency that conflicts with our stack?Stack fit. Assumes a Laravel REST API backed by Eloquent models — a direct match if that is our shape. It does not fit non-Eloquent data sources, GraphQL, or endpoints requiring bespoke response composition. Before committing, pin the package against our exact framework/PHP matrix and confirm the pagination envelope matches our API contract; if it does not, budget for a response-mapping adapter rather than fighting the vendor class.
Migration path. Treat this as an additive, opt-in pattern, not a refactor of existing controllers. For brownfield, introduce it behind a thin local base class (e.g., App\Http\Controllers\Api\ApiController extends BrunoController) so the vendor dependency is isolated in one file and can be swapped for spatie/laravel-query-builder later without touching every endpoint. For greenfield, adopt it directly but keep the same local-subclass seam. Do not attempt a big-bang migration of existing endpoints — the value per endpoint is modest and the regression surface is the whole API contract.
Compatibility. Verify: framework constraint, PHP floor, pagination response shape, interaction with existing global scopes and soft deletes, and whether include/eager-load declarations collide with our own relationship-loading conventions. Any existing custom base controller is a hard blocker for the inheritance model and should push us toward the fluent/wrapper form instead. Test against one representative endpoint with nested includes and multiple filters before wider rollout.
Sequencing.
spatie/laravel-query-builder at the end of the first module — if it wins on contract fit or maintainability, the local seam makes the swap cheap.Maintenance. The package becomes part of the request path, so we own its operational risk whether or not we own the code. With a small community and few dependents, upstream fixes for framework upgrades and security issues may lag. Mitigation: isolate behind a local base class, pin the version, and budget engineering time to fork or vendor if upstream stalls. Assume we are the de facto maintainers of our usage.
Support. No commercial support; reliance on maintainer goodwill and GitHub issues. That is acceptable for a convenience layer but not for anything on a critical, high-traffic path without a fallback. Keep the swap-to-spatie path documented and tested at least once.
Scaling. Pagination itself is standard and safe (offset-based). The scaling risks are in the filter layer: filters on unindexed columns, deep pagination offset cost, unbounded include lists causing heavy eager loads, and clients requesting large per_page. Enforce a server-side cap on per_page, whitelist includes, add rate limiting, and monitor slow-query logs on filtered endpoints. Filter complexity is bounded by the whitelist, which is the package's main safety property — verify it is actually enforced.
Failure modes.
Ramp-up. Low. The property-based configuration is learnable in an afternoon, and the mental model (whitelist filters/sorts/includes, return paginated JSON) matches what most Laravel developers already expect. The onboarding cost is in conventions — naming of query parameters, pagination shape, and authz rules — which must be documented once and enforced via contract tests. Estimate roughly one sprint of one engineer to spike, wrap, document, and land the first two or three endpoints; marginal cost per endpoint thereafter is small.
How can I help you explore Laravel packages today?