Laravel Adjacency List Laravel Package

Product Decisions This Supports

• Feature investment: build vs. buy for hierarchy features. Any roadmap item involving nested data — category/menu trees, org charts, page hierarchies, threaded comments, referral/affiliate trees, permission inheritance, bill-of-materials, taxonomy trees — can be scoped in days rather than weeks. The package turns "recursive relationships" from a bespoke SQL project into a trait on an Eloquent model.
• Data model decision: keep the simple parent_id adjacency list. This removes the usual pressure to adopt nested sets or closure tables just to avoid N+1 recursion. That means no extra tables, no maintained path/left-right indexes, no migration churn — a direct reduction in schema complexity and long-term maintenance cost.
• Build vs. buy: avoid hand-rolled CTEs. Without it, engineers typically either (a) loop in PHP fetching parents/children level by level (N+1, slow, memory-heavy), or (b) write raw recursive CTE SQL per query (unmaintainable, DB-specific, untested). This package provides a tested, version-maintained abstraction over both.
• Roadmap sequencing. Because the dependency is cheap and additive, hierarchy-dependent epics (e.g., "nested categories," "org structure," "comment threads," "subtree permissions") can be pulled forward without a platform investment. It also de-risks later features like subtree analytics (withCount('recursivePosts')), which often appear as follow-on requests.
• API and UX decisions. The package ships depth, path, and custom path columns plus toTree() nested serialization. That directly informs API contract decisions — you can offer "give me the subtree, nested, 3 levels deep" as a single endpoint instead of client-side assembly.
• Performance and guardrail decisions. withMaxDepth() lets you cap query cost at the product level ("show 3 levels, then lazy-load"), withQueryConstraint() supports business rules like "skip inactive users and their descendants," and cycle detection defines whether user-editable hierarchies are safe to ship without a data-integrity review.
• Portability decision. Supported on MySQL 8.0+, MariaDB 10.2+, PostgreSQL 9.4+, SQLite 3.8.3+, SQL Server 2008+, so this is not a commitment tied to one database. That matters if the platform roadmap includes migrating managed DB providers.
• Dependency posture decision. MIT license, no paid tier, no vendor lock-in — it is a trait applied to models, so removal is a contained refactor rather than a re-architecture.

When to Consider This Package

Adopt when:

• The product has, or is about to have, genuinely hierarchical data: one parent per node (trees) or multiple parents per node (graphs/DAGs).
• The stack is Laravel 5.5+ through 13.x on a database with CTE support (MySQL 8.0+, MariaDB 10.2+, PostgreSQL 9.4+, SQLite 3.8.3+, SQL Server 2008+).
• You want to stay on Eloquent and keep parent_id-style schemas rather than introduce closure tables or nested sets.
• You need subtree queries in both directions (ancestors and descendants), depth- and path-aware results, nested JSON output, breadth-first or depth-first ordering, or recursive aggregates for dashboards and filters.
• You need recursive access to related models, not just the tree itself (hasManyOfDescendants, belongsToManyOfDescendants, morphToManyOfDescendants) — e.g., "all posts by a user and everyone under them."
• You want cycle detection and depth caps as configuration rather than bespoke code, especially if end users can rearrange the hierarchy.

Look elsewhere when:

• The database lacks CTE support (e.g., MySQL 5.7 or older) — this is a hard blocker, not a tuning issue.
• The team is not on Laravel/Eloquent, or the data layer is deliberately framework-agnostic (repository/Doctrine pattern). You would be paying for an Eloquent trait you cannot use.
• You need true graph algorithms — shortest path, weighted traversal, connectivity analysis — rather than parent/child traversal. This is a traversal library, not a graph engine.
• The hierarchy is huge, read-hot, and write-cold, and you need O(1) subtree reads. In that case a materialized path or closure table with maintained indexes can outperform recursive CTEs; validate with your own data volume.
• You need multi-parent graphs on SingleStore (trees only) or expect to run hierarchy queries from a BI/warehouse layer outside the app.
• Organizational policy prohibits third-party runtime dependencies, or the team cannot absorb a dependency whose release cadence tracks Laravel majors.

Adoption checklist before committing:

• Confirm the production database version and CTE support in every environment, including CI and local SQLite.
• Pin a version from the compatibility matrix that matches your Laravel major; treat Laravel upgrades as requiring a package bump.
• Note the dataset reports 0 dependents despite ~1.6k stars and an active release line — treat that as a measurement gap, not evidence of low use, but verify Packagist download counts and scan the issue tracker for your database and Laravel version before adoption. Maturity signals are otherwise strong: MIT license, releases spanning Laravel 5.5 through 13.x, PHPStan level 9, published code coverage, CI badge.
• Add integration tests around your deepest and widest real hierarchies; benchmark the tree endpoints with production-shaped data.
• Enable cycle detection wherever users can set a parent, and set withMaxDepth() defaults so no endpoint can traverse unbounded.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can deliver the hierarchy features already on the roadmap — nested categories, org structures, comment threads, inherited permissions, referral trees — for a fraction of the estimated effort, using a free, MIT-licensed, actively maintained open-source library that plugs into our existing Laravel codebase. It requires no new infrastructure, no schema redesign beyond the parent reference we already use, and no vendor contract. The primary risks are a database version prerequisite and the usual cost of adding a dependency, both of which we can retire in a contained refactor if needed.

For engineering leadership:

• It is a trait plus query scopes on existing models — no new services, no queues, no migrations beyond the parent_id column you already have.
• It replaces two bad patterns we would otherwise write by hand: level-by-level PHP recursion (N+1) and hand-written recursive CTE SQL per query.
• It ships guardrails we would otherwise build: withMaxDepth() for cost caps, withQueryConstraint() / withInitialQueryConstraint() / withRecursiveQueryConstraint() for business filtering, and configurable cycle detection with an is_cycle flag.
• Compatibility matrix is documented per Laravel major (Laravel 13 → 1.26 down to 5.5–5.7 → 1.0), so upgrade planning is explicit rather than discovered.
• Quality signals: CI, code coverage reporting, PHPStan level 9, stable tagged releases.

For the product team:

• Unlocks familiar, high-value UX with less engineering: expandable trees, breadcrumbs (via path / custom paths like slug_path), "show all descendants," "count everything under this node," and subtree-wide bulk actions like deactivate or delete.
• Enables depth-aware product rules: "show 3 levels free, load more on demand" maps directly onto depth constraints rather than custom backend work.
• Makes user-editable hierarchies safe to ship by giving us loop protection and explicit cycle reporting instead of silent infinite loops.

Known risks to state plainly:

• Database floor: MySQL 8+/MariaDB 10.2+/PostgreSQL 9.4+ (or SQLite/SQL Server equivalents). Any legacy MySQL 5.7 footprint blocks adoption.
• Recursive CTEs cost more as trees grow; we should agree on depth caps and benchmark before launch.
• SingleStore supports trees only, not graphs.
• Low reported dependent count in our dataset should be verified before we cite adoption as a maturity signal; the maintenance signals (release cadence, static analysis, coverage) are the stronger evidence.