Eloquent Eager Limit X Laravel Cte Laravel Package

Product Decisions This Supports

• Feature unblock: per-parent "top N" relations. Eloquent's native ->with(['comments' => fn ($q) => $q->limit(3)]) limits globally to three rows, not three per parent. The underlying capability delivers the per-parent semantics users actually expect — the query shape behind activity feeds, inboxes, "latest 5 orders per customer," per-tenant rollups, and dashboard cards. Treat this as a shipped product capability, not a performance tweak: it changes what we can promise.
• Feature unblock: recursive and hierarchical data. The CTE half enables WITH / WITH RECURSIVE through the query builder — org charts, category trees, threaded comments, referral chains, BOM traversal. Today these are typically built with multiple round trips or PHP-side recursion that degrades past a handful of levels; that ceiling is a quality problem users feel.
• Roadmap sequencing and deferral. Adopting this de-risks a "rich feed / per-entity latest-N / hierarchy view" item and can push back a denormalization table, a materialized-view pipeline, or a search-cluster introduction by one or more quarters — a real schedule and infrastructure saving. Conversely, if the roadmap contains no top-N or hierarchy requirement, there is no product reason to carry the dependency. "Not now" is a legitimate, defensible answer here.
• Build vs. buy — with a twist. In-house, the capability is roughly 1–3 weeks of engineering plus permanent maintenance. But this specific artifact is a thin compatibility shim between two upstream libraries by the same author. The correct buy decision is usually one of the upstream packages; this bridge earns its place only when both capabilities are needed and they collide on our Laravel version. Separating "buy a capability" from "tolerate an artifact" keeps the roadmap honest.
• Architecture signal worth a design conversation. The existence of a merge package is itself information: two advanced query-builder extensions override the same SQL compilation path. That flags a real question — how deep does the feed/reporting layer sit inside Eloquent versus a dedicated read model or reporting service? Raise it now, while the surface is small.
• Database platform becomes a product constraint. Window functions and CTEs require MySQL 8+, PostgreSQL, SQLite 3.25+, or SQL Server. A MySQL 5.7 deployment target is a hard blocker and forces a hosting/upgrade roadmap conversation with cost and migration risk attached. Decide that deliberately, not as a side effect of a composer require.
• Scope decision: pilot dependency vs. platform standard. The right PM output is a scoped approval — pinned, hidden behind one internal helper, attached to specific endpoints — rather than blessing it as a house standard. That keeps removal a one-file change and prevents transitive adoption by convenience.

When to Consider This Package

Adopt when:

• You have a confirmed, simultaneous need for per-parent eager-load limits and CTE queries in the same codebase, and you've verified the two upstream packages actually conflict on your Laravel version. Otherwise you are adding a layer you don't need.
• Query volume is real and measurable: N+1 pressure, p95 latency or memory hits from fetch-then-slice-in-PHP, or relation collections large enough that limit() semantics change user-visible outcomes.
• You're on MySQL 8+ / PostgreSQL / SQLite 3.25+ / SQL Server and can pin that database floor as an explicit platform commitment.
• The team accepts dependency-ownership risk: 6 stars, 0 dependents, single maintainer, last release 2023-02-12. Practically that means pinning the exact version, adding it to the Laravel-major upgrade checklist, and budgeting roughly a day to vendor or reimplement the trait if upstream stalls.
• MIT licensing and single-maintainer provenance clear dependency policy — or you plan to copy the trait in-house, which is viable because the surface area is small.
• The fallback (over-fetch and slice in PHP) is quantifiably worse for the affected endpoints, and you can show that in a spike rather than assert it.

Look elsewhere when:

• You only need one behavior. Use staudenmeir/eloquent-eager-limit or staudenmeir/laravel-cte directly — both carry materially more usage and community validation than this merge. This is the single most likely correct answer.
• You're on Laravel 11/12 and haven't tested. A February 2023 release predates those majors; a package that hooks internal grammar compilation is exactly what breaks on a major bump. Treat compatibility as unproven — spike it in a branch, never on the critical path.
• MySQL 5.7 or older SQLite is in the fleet. No window functions, no CTEs; the package cannot deliver its core value at any price.
• A native or simpler path already covers it. latestOfMany() / ofMany(), a whereIn subquery, or a precomputed summary table often solves "latest one per parent" with zero new dependencies. If the requirement is literally "latest 1," this is overkill — check that first, because it is the cheapest possible outcome.
• A search index exists or is planned. If Meilisearch/Elasticsearch is on the roadmap for feeds or top-N, that is usually the better operational home for the read path than ORM-level SQL surgery.
• Your dependency bar rejects near-zero-adoption packages. In a large org with formal supply-chain review, 0 dependents and a stale release will fail review. The right move is then an in-house trait or vendored fork — the logic is small enough that this is a legitimate build decision, not a compromise.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, MIT-licensed Composer dependency that unlocks two things we currently cannot express cleanly in our ORM: "the latest N items for each customer/account/post," and recursive queries over hierarchical data. It lets us ship per-entity feeds and hierarchy views without standing up a search cluster or a denormalization pipeline — a meaningful schedule and infrastructure saving. The risk is maintenance, not capability: it is a low-adoption package with a single maintainer, zero dependents, and a 2023 release. Mitigation is cheap and bounded — pin the exact version, add it to the Laravel-upgrade checklist, and hold a one-day in-house fallback. Recommendation: green-light as a scoped, pinned dependency for the feed work, not as a platform-wide standard.

To engineering (three things to verify before merge):

1. The database floor — MySQL 8+ / Postgres / SQLite 3.25+ / SQL Server, since window functions and CTEs are mandatory. A MySQL 5.7 estate disqualifies this outright.
2. Laravel-version support — the last tag predates Laravel 11; confirm it against our target before planning around it.
3. The generated SQL itself, via toSql() or the query log. Confirm the PARTITION BY key and the ROW_NUMBER predicate are what we would hand-write — a wrong partition produces plausible-looking wrong data rather than an error, which is the failure mode to fear here.

And two structural asks: prefer the upstream packages unless we genuinely need both; and put the capability behind one internal helper so no call site imports the vendor trait, making removal or a fork a one-file change. Add a CI test asserting generated SQL for representative queries so a Laravel bump fails loudly at PR time instead of in production.

One-line framing: buy the capability, pin the artifact, and hide it behind one internal helper so removal is a one-file change.