Laravel Aggregated Queries Laravel Package

Product Decisions This Supports

• Where to spend the performance budget. Gives you a concrete third option between "add caching" and "add infrastructure" for slow read endpoints: collapse N relationship queries into one SQL statement using JSON aggregation (json_agg / JSON_ARRAYAGG / json_group_array). That is a scoped, reversible engineering task rather than a new Redis cluster or read replica.
• API response shape / read-model design. Nested JSON resources (order → items → product) are exactly what JSON aggregation returns cheaply. This package makes "return one nested payload" the low-cost default instead of "return flat rows and let the client join," which is a product-facing decision about client complexity and mobile payload strategy.
• Build vs. buy for the read layer. The alternative is hand-rolling dialect-specific aggregate SQL inside repository classes. Buying means adopting a small MIT dependency; building means owning ~a few hundred lines of SQL you will maintain across MySQL/Postgres/SQLite. This package lets you defer that decision cheaply — if you wrap it.
• Whether Eloquent stays the read layer. If a hot list endpoint needs 6 queries today, the roadmap question is "optimize Eloquent," "introduce a CQRS read model / query builder," or "nothing." This is the cheapest probe of option one before committing to a bigger architectural change.
• Sequencing perf work vs. feature work. A one-endpoint spike is a small, time-boxed bet with a measurable before/after (query count, p95, DB CPU) that can justify or kill a larger performance initiative.
• Dependency risk posture. 10 stars, 0 dependents, opportunity score 1.03, single maintainer: treat this as a technique you evaluate, not infrastructure you standardize on. The decision it supports is "adopt behind an internal abstraction with a fork-friendly license," not "make this a platform standard."

When to Consider This Package

Consider it when:

• You have read-heavy, low-write endpoints with 3+ eager-loaded relations per parent (belongsTo, hasOne, hasMany) and a query count you actually monitor (Telescope/Debugbar, DB::listen).
• Per-query latency dominates — managed/remote DB, serverless drivers (PlanetScale, Neon, Aurora Serverless), cross-region app-to-DB hops — so 6 round trips × 5 ms is real p95, not noise.
• You are on Postgres or MySQL 8 (verify MariaDB / SQL Server / older MySQL behavior explicitly before committing).
• You have already exhausted the cheap wins: indexes, pagination, select() narrowing, withCount instead of loading, and Laravel's native chaperone() for hasMany chains.
• You can put the call behind a repository/query object and pin the version.

Look elsewhere when:

• Related models must remain fully live Eloquent objects after load — chunked updates, ->each->save(), accessors/casts/$appends on children, nested eager loads inside the aggregated relation, or whereHas on already-loaded relations. Aggregation returns decoded JSON; verify hydration, casting, and global-scope/soft-delete behavior in a spike before assuming parity.
• You need nested relations within the aggregated relation, or pagination over the child collection.
• Laravel's built-in eager loading plus chaperone() already gets you most of the win at zero dependency cost.
• Your real bottleneck is serializer overhead, payload size, or a missing index — aggregation will not move those.
• Your dependency policy cannot absorb an unmaintained single-maintainer package (0 dependents means no downstream canaries).

How to Pitch It (Stakeholders)

To executives: We have a specific class of slow endpoints where the database round trips, not the database work, drive latency. This package is a small, MIT-licensed utility that lets one request fetch a parent and its children in a single query instead of six. It is a time-boxed experiment with a measurable outcome — query count and p95 on one endpoint — and no infrastructure spend. It is not a platform commitment; it is reversible and license-permissive enough that we can fork it if the maintainer walks away. Recommendation: fund a one-sprint spike, decide on data.

To engineering: Drop-in optimization for belongsTo/hasOne/hasMany eager loads that swaps Eloquent's per-relation IN (...) queries for a single JSON-aggregate statement, with the dialect-specific SQL handled for you. Costs and caveats: unproven dependency (10 stars, 0 dependents), so pin the version and isolate it behind a query object so we can swap to native chaperone(), hand-rolled SQL, or a read model later. Before adoption we need a benchmark on a real endpoint, contract tests asserting the JSON shape and model hydration (casts, accessors, soft deletes, global scopes), and a feature flag for rollback.