Eloquent Eager Limit X Laravel Adjacency List Laravel Package

Product Decisions This Supports

• It converts a recurring "preview" pattern from an infrastructure problem into a sprint task. The features that need this package are all the same shape: the three most recent replies in a thread, the first four children per category tile, a capped reporting line on an org chart, a two-level mega-menu, a referral chain truncated at N. Each requires a LIMIT applied per parent on a recursively eager-loaded relationship — the exact intersection where eloquent-eager-limit (per-parent limit via window functions) and laravel-adjacency-list (recursive relationships over parent_id) collide at the trait level. This bridge exists so those two compose instead of conflicting, which means the feature is scoped as product work rather than as a SQL research project.
• It removes the accidental default that would otherwise ship. Without it, the path of least resistance is to hydrate the full subtree and slice in PHP. That decision looks free in a demo, is invisible in code review, and surfaces post-launch as p95 latency and database spend on exactly the pages you want to be fast — feeds, category landings, navigation. Naming this package in the design doc is how a PM forecloses that outcome before it is baked into three surfaces.
• It makes build-vs-buy defensible in one slide. The real options are (a) hand-rolled ROW_NUMBER() OVER (PARTITION BY parent_id) plus custom hydration, (b) load-everything-and-slice, or (c) one Composer dependency. Option (b) is the silent default; option (a) is a week of query plumbing with no product surface; option (c) is free and MIT-licensed. That reframes the roadmap conversation from "do we have database bandwidth this quarter" to "does this feature earn its keep" — the question you actually want the room arguing about.
• It keeps hierarchy features inside the stack you already operate. Nested taxonomy, threaded conversation, multi-level navigation, hierarchy-aware pickers and breadcrumbs do not become a pretext for a headless CMS, a graph database, or a content platform. That is deferred infrastructure spend — a hiring, procurement, and on-call commitment — not merely engineering convenience. For a PM, avoiding a new datastore is usually worth more than the feature that triggered it.
• It gives you a written scoping line to end case-by-case debate. This is a query-shaping utility over adjacency lists. It supports bounded-depth, bounded-fan-out presentation. It does not support "count every ancestor of every node," shortest-path, cycle analytics, or recommendation traversal. Put that line in the roadmap doc so "tree features we can ship now" and "graph features that need their own evaluation" stop being relitigated per request.
• v1.2's "graph relationships" is prototyping budget, not a roadmap commitment. Treat it as license to time-box a proof of concept for a connected-data idea. It rides the same adjacency-list foundation and inherits the same ceilings — do not let it become a customer-facing graph feature by accretion.
• Approval is low-blast-radius and high-reversibility — which is itself the PM-relevant fact. Traits are additive: no schema migration, no backfill, no dual-write, no data project. Rollback is a deploy. That means you can authorize an evaluation without an architecture review board or a procurement cycle, on the single condition that you accept ownership of the code if upstream goes quiet.

When to Consider This Package

Consider it when:

• Your hierarchy is already an adjacency list — a parent_id or equivalent column on the same table. If you are on nested set, closure table, or materialized path, the recursive half buys you nothing and the underlying primitive is wrong for the job.
• The requirement is bounded and presentational. Latest N children, first N descendants, two- or three-level previews. The value here is query shape, not analytical depth.
• You are on Laravel with window-function-capable SQL — MySQL 8+, Postgres, SQLite 3.25+, SQL Server. Window functions are non-negotiable; MariaDB and MySQL 5.7 are out.
• You want zero model churn. Drop-in traits matter most when the tree models are shared across teams and you cannot ask everyone to refactor.
• Absorbing an unmaintained dependency is cheaper than owning an equivalent query layer — and you have a named engineer accountable for upgrades. At 14 stars, 0 dependents, one maintainer, pre-2.0, and a last release in May 2023, that trade must be made explicitly rather than by default.
• You will run a short spike against realistic volumes. Include at least one high-fan-out hub node; uniform test data flatters this package badly.

Look elsewhere when:

• You need unbounded traversal, shortest-path, cycle detection, or high-volume graph queries. Use a graph store, or hand-written recursive CTEs with expert review.
• You need paginated totals across a tree ("showing 1–10 of 4,382 descendants"). Per-parent LIMIT plus global pagination is genuinely awkward; a materialized path or a different data model is the honest answer.
• Fan-out is extreme. Benchmark the hub-node case specifically before committing — this is where the recursive CTE plus window function plus limit query shape degrades.
• Published stability guarantees, a support SLA, or a security policy are hard requirements. They are not met. Note the caveat: the maintainer is a well-known, prolific Laravel ecosystem author, so bus-factor risk is materially better than raw metadata implies — but there is no commercial backing and no release since May 2023.
• Your Eloquent lifecycle is heavily customized — multi-tenancy global scopes, soft-deleted tree nodes, audit trails, Nova or Lighthouse integrations. Relationship traits intervene in resolution, and silent scope bypass on traversed records is the most likely failure mode.
• The bridge's Laravel support matrix is stale relative to your target version. Bridge packages must be re-released per Laravel major, so Laravel 11/12 support is unproven until you read composer.json — not the README. Close this before you spec the feature, not mid-sprint.

How to Pitch It (Stakeholders)

For executives. This is a small, free, MIT-licensed PHP library that lets us ship tree-shaped product experiences — threaded conversations, nested categories, org structures, preview navigation — inside the Laravel application and database we already run. The commercial point is simple: the obvious way to build these features reads far more data than the screen shows, and that cost only appears after launch, as slow pages and database spend. This library makes the efficient query the default. The price is one Composer dependency and a short validation spike: no new infrastructure, no vendor contract, no data migration. Recommendation: approve a time-boxed evaluation on one real feature, not a blanket engineering standard.

For engineering. It composes two packages from the same maintainer — eager-load limiting and adjacency-list trees — so you can attach a LIMIT to a recursively eager-loaded relationship without falling into N+1 or hand-writing window functions. Integration is composer require plus traits on the tree model; no schema change, no backfill. Three things to verify before we commit: the Laravel/PHP matrix in composer.json for the bridge and both upstream packages; that our engine supports window functions; and that the traits coexist with our global scopes and soft deletes. Pin the exact version as a four-tuple in the PR (bridge, eager-limit, adjacency-list, Laravel), wrap it in an internal abstraction so swapping in a hand-rolled ROW_NUMBER() scope is a one-file change, and spike on one model in one bounded context — not on models other teams depend on.

For product and roadmap. This unblocks a class of preview experiences we have been deferring: threads that show a few replies behind a "see all," category pages with per-section featurettes, hierarchy-aware pickers and breadcrumbs, capped reporting lines. It does not unblock deep traversal, recommendations, or hierarchy analytics — those keep their own evaluation and stay off the near-term roadmap. The move is to pick the single highest-value tree feature, build it behind a flag against realistic data volume, and measure query count and p95 latency before widening use. Document a depth ceiling and test depth 2+ explicitly; do not assume limit() composes below direct children.

Risks to flag. Maturity: single maintainer, no release since May 2023, a 1.x API that may still move, and release notes that appear inherited from the upstream adjacency-list package rather than written for the bridge — expect engineers to read upstream source for behaviour questions. Correctness: cycles, soft-deleted nodes, and scope bypass on traversed records are unverified, and scope bypass is the most likely silent defect. Coupling: relationship traits on domain models are invasive to remove, so exit cost is a query-layer rewrite, not a version bump. Mitigations: an exact version pin recorded as a four-tuple, an internal abstraction at the call site, a flag-guarded pilot on one non-critical feature, and a documented fallback — a hand-written adjacency table plus an Eloquent scope, roughly the same effort as the integration minus the maintenance dependency.