Eloquent Eager Limit X Laravel Adjacency List Laravel Package

Technical Evaluation

Architecture fit. This is a bridge, not a framework: it makes staudenmeir/eloquent-eager-limit (per-parent LIMIT via ROW_NUMBER() OVER (PARTITION BY ...)) compose with staudenmeir/laravel-adjacency-list (recursive relationships over parent_id). The fit is high and narrow — Laravel applications that already store hierarchies as adjacency lists and need bounded, presentational reads: latest N replies per thread, N featured children per category, capped org reporting lines, two-level menus. The fit is zero if the hierarchy is a nested set, closure table, or materialized path, or if it hasn't been modelled yet.

The real architectural fact for a TPM is the coupling: domain model → bridge → two upstream packages → Laravel version → database engine with window functions. That is a five-way compatibility matrix behind a single composer require, and tracking it — not reviewing trait syntax — is the TPM job here.

Integration feasibility. Code effort is genuinely low: composer require, one trait on the target model, standard eager-load closures with limit(). No schema migration, no backfill, no dual-write. The work is validation, and it should be treated as a spike with explicit exit criteria rather than an implementation task.

Technical risk, ranked by likelihood × blast radius:

• Compatibility drift (high). Bridge packages must be re-released per Laravel major. Last release is 2023-05-14; Laravel 11/12 support is unproven until read from composer.json for the bridge and both upstream packages. A stale bridge either blocks our next framework upgrade or forces us to fork and own it.
• Query shape (medium-high). Recursive CTE + window function + limit is a heavyweight query. Correct by construction, but performance is data-shape dependent; hub nodes and deep trees are where it degrades, and uniform test data will flatter it.
• Scope bypass (medium, silent). Relationship traits intervene in query resolution. Multi-tenancy global scopes, soft deletes, and audit scopes on traversed records are the most likely silent defect — wrong-but-plausible results, not errors.
• Abandonment (medium). 14 stars, 0 dependents, one maintainer, pre-2.0, no SLA or security policy. The maintainer is a well-known, prolific Laravel author, so bus factor is materially better than metadata implies — but there is no commercial backing and release notes appear inherited from upstream (the v1.2 "graph relationships" line belongs to the adjacency-list package), so expect engineers to read source for behaviour questions.
• Reversibility (low). Traits are additive; rollback is a deploy, not a data project. This is the package's strongest risk argument — provided we keep the old query path alive behind the abstraction.

Key questions to close before speccing the feature:

1. What Laravel/PHP versions does this specific bridge release support, and do they intersect with both upstream packages' constraints? Read manifests, not the README.
2. Which database engine and version are we on? Window functions are non-negotiable — MySQL 8+, Postgres, SQLite 3.25+, SQL Server. MariaDB and MySQL 5.7 are out.
3. Does limit() compose with recursive relationships at depth 2+, or only for direct children? Test and document the depth ceiling.
4. What SQL is actually generated, and does EXPLAIN show index usage on the parent column?
5. Do global scopes, soft deletes, and tenancy predicates survive traversal unmodified?

Integration Approach

Stack fit. Adopt only where three conditions hold simultaneously: the tree is already an adjacency list; the requirement is bounded and presentational (latest N, first N, two-to-three-level preview); and the database supports window functions. If any of the three fails, stop — the package buys nothing and adds a dependency.

Migration path. There is no data migration. The path is: add the trait to one model in one bounded context, keep the existing query path intact behind a thin internal wrapper (a repository method or Eloquent scope), and switch via feature flag. The wrapper is the important engineering instruction — it makes swapping in a hand-rolled ROW_NUMBER() scope a one-file change instead of a call-site sweep, and it converts an invasive trait dependency into a reversible one.

Compatibility sequencing. Do these in order; each can kill the initiative cheaply:

1. Read composer.json for bridge and both upstreams; map Laravel/PHP constraints against our target version. If Laravel 11/12 is unsupported, decide now between staying pinned, forking, or writing the scope ourselves — that decision belongs before the sprint, not in it.
2. Confirm database engine and version support window functions in our actual environments (including CI and any read replicas).
3. Spike on one non-critical model with realistic volume, including at least one high-fan-out hub node. Uniform test data will hide the failure mode.
4. Verify scope and soft-delete behaviour explicitly with tests that assert row contents, not just counts.
5. Test depth 2+ and record the depth ceiling in the code and the docs.
6. Record the exact pinned four-tuple in the PR: bridge, eager-limit, adjacency-list, Laravel.

Compatibility risk to accept explicitly. Three packages must move in lockstep against a moving framework. If we adopt, we accept an obligation to re-evaluate at every Laravel major. Write that into the team's upgrade checklist the day we merge, or it becomes an emergency later.

Operational Impact

Maintenance. Low ongoing code maintenance, non-trivial upgrade maintenance. The dependency is small and stable, but it is pinned and pre-2.0, and the bridge trails upstream releases. Assign a named engineer accountable for the pinned version and for the Laravel-major re-check. Budget a fork contingency: the fallback is a hand-written ROW_NUMBER() OVER (PARTITION BY parent_id) scope — roughly the same effort as the integration, minus the dependency. That fallback should be documented before adoption, not after abandonment.

Support. No SLA, no security policy, no commercial backing. Support model is "read the upstream source" — the bridge's own release notes are thin or inherited. That's acceptable for a small team absorbing the dependency; it is not acceptable where a published stability guarantee is a hard requirement. Escalation path is internal ownership, not vendor contact.

Scaling. Two pressure points. First, fan-out: a hub node with thousands of children under a recursive CTE plus window function is where latency appears; benchmark that case specifically. Second, depth: cost compounds with recursion depth, and limit() may not compose below direct children. Both should be encoded as guardrails — a documented depth ceiling and a monitored query-count/p95 budget per request — rather than discovered in production.

Failure modes, in order of how quietly they fail:

• Silent scope bypass — traversed records ignoring tenancy or soft-delete predicates. Returns plausible, wrong data. Mitigate with content assertions in tests, not count assertions.
• Silent correctness gap at depth — limit() not applying below direct children, producing over-fetch that looks like working output. Mitigate with explicit depth-2+ tests.
• Cycles — unverified; a malformed tree can produce runaway recursion. Mitigate with data integrity constraints on the parent column.
• Performance cliff on hub nodes — correct results, unacceptable latency. Mitigate with a realistic-volume benchmark and EXPLAIN review pre-merge.
• Upgrade blockage — a stale bridge halting a Laravel major. Mitigate by re-checking the pinned matrix every framework upgrade.

Ramp-up. Low: an Eloquent-fluent engineer can integrate in hours, and the mental model (traits + eager-load closures) is familiar. The learning cost sits in the validation, not the API — window-function SQL, recursive CTE query plans, and scope interaction. Plan a short time-boxed spike on one model in one bounded context, behind a flag, with query count and p95 measured against realistic data. If the spike passes, widen deliberately. Note the scoping line for roadmap reviews: this supports bounded-depth, bounded-fan-out presentation. It does not support hierarchy analytics, shortest-path, cycle detection, per-tree paginated totals, or recommendation traversal — those need their own evaluation and should stay off the near-term roadmap regardless of how well the pilot goes.