Product Decisions This Supports
- Feature sizing for "computed column" surfaces. Dashboards, list views, and API index endpoints often need derived fields — last activity date, latest invoice status, count of open tickets, most recent note author. This package lets those be declared on the model and resolved inside the same SQL query, so a PM can scope these features as "one query + a few model declarations" rather than a new endpoint, a denormalization job, or a per-row PHP loop.
- Performance/roadmap trade-offs on paginated endpoints. The real product value is avoiding N+1 loads and PHP-side post-processing on paginated lists, where correctness of sorting and filtering depends on the value being computed in the database. This directly affects page latency on the screens users hit most, which is usually a retention and conversion lever rather than a technical nicety.
- Build vs. buy for the query layer. Adoption cost is roughly a day of spike plus a handful of model changes; building an equivalent reusable abstraction in-house is a multi-sprint effort that will look almost identical. The buy case is strong on engineering hours — but only if the lifecycle risk below is accepted.
- Consistency decisions across the codebase. It standardizes how subquery-derived attributes are defined (one trait/convention instead of ad-hoc
selectRaw strings scattered across controllers and repositories), which reduces review friction and makes derived fields reusable across scopes and eager loads.
- Explicit non-goals to keep on the roadmap. It does not solve caching, read-model denormalization, full-text search, or cross-service data. If a feature's real bottleneck is index design or a reporting warehouse, this package is a distraction and should be scoped out early.
When to Consider This Package
Consider it when all of the following hold:
- You are on a legacy Laravel version (roughly 5.5–6.x) where native
withCount / withSum / withMax / selectSub ergonomics are insufficient or you need richer per-model declarations.
- The same derived columns recur across many endpoints, so a declarative, reusable definition genuinely saves code rather than adding an abstraction over three call sites.
- Your team is small enough that a vendor-and-fork decision is cheap, and you are willing to pin the dependency, add tests around it, and own patches.
Look elsewhere when:
- You are on Laravel 8+ — native
withCount, withSum, withAvg, withMax, withMin, and selectSub cover the large majority of cases with zero dependency risk.
- You need maintained dependencies with active security and compatibility coverage. 19 stars, a last release of 2019-10-31, and a low evaluation score (0.245) mean it will not track new Laravel or PHP releases; budget for it breaking on upgrade.
- A more established alternative fits better (e.g., Staudenmeir's eager-load/relationship packages,
spatie/laravel-query-builder for API filtering and sorting, or a plain query-object/repository layer).
- The performance problem is actually schema, indexing, or denormalization — a subquery wrapper will not fix it.
- Your platform team has a standing rule against unmaintained third-party packages in the request path.
How to Pitch It (Stakeholders)
To executives: This is a small MIT-licensed library that lets us add calculated fields to list and dashboard screens — "latest status," "open item count," "last activity" — in a single database query instead of dozens. The upside is shipping several of these features faster and making our busiest screens noticeably snappier, at effectively zero licensing cost. The caveat is that it is a niche, unmaintained project last updated in 2019, so we should treat it as a tactical shortcut we own and can replace, not a platform bet.
To engineering: It gives us a declarative way to attach subquery-derived attributes to Eloquent models, cutting repeated selectRaw/selectSub boilerplate and eliminating N+1s on paginated endpoints. The trade-off is explicit: stale dependency, thin community, no upstream support. Recommendation is a timeboxed spike against one or two real endpoints, then either vendor/fork with test coverage and a version pin, or fall back to native selectSub / withCount / withSum if we are on Laravel 8+. Do not adopt it as a foundational dependency without an owner and an exit plan.
Decision requested: approve a short spike, with adoption contingent on it demonstrably replacing existing raw-SQL patterns in at least two places — otherwise standardize on native Eloquent aggregates and close this out.