Download the PHP package tetthys/eloquent-hierarchy without Composer

Eloquent Hierarchy (Adjacency List)

A lightweight, high-performance Eloquent trait for self-referential (recursive) models.
It provides parent/children relations, O(1) hasParent(), EXISTS-based hasChildren(), depth calculation, ancestor/descendant utilities (CTE fast path + BFS fallback), and handy query scopes.

Features

• Relations: parent() and children() (self-referencing)
• Fast checks: hasParent() (O(1), no query), hasChildren() (single EXISTS)
• Depth: depth() with eager-load shortcut, cycle/missing-parent guards
• Ancestors/Descendants:
  • Fast path: single-query recursive CTE (MySQL 8+, PostgreSQL, SQLite)
  • Fallback: batched BFS traversal for engines without recursive CTE
  • Stream descendants as LazyCollection
• Scopes: roots() (no parent), leaves() (no children)
• Customizable: override FK/PK naming via constant or methods
• External SQL templates: editable CTE SQL in src/Sql/*.sql

Requirements

• PHP 8.0+ (tested up to PHP 8.3+)
• Laravel / Illuminate Database v10+ (works with 10 / 11 / 12)
• Database:
  • CTE fast path: MySQL 8+, PostgreSQL, SQLite
  • BFS fallback: works anywhere Eloquent runs (e.g., SQL Server)

The package ships SQL templates for CTE queries in src/Sql/descendant_ids_cte.sql and src/Sql/descendants_exist_cte.sql.

Installation

`

If you are developing this repo locally (using the included Docker setup) and see Composer plugin prompts (e.g., for Pest), allow it explicitly:

File Layout (key parts)

HasHierarchy loads the SQL templates at runtime and replaces placeholders like {{table}}, {{pk}}, {{parent_fk}}, and {{depth_limit}}.

Quick Start

1) Add the trait to your model

2) Migration (example)

3) Basic usage

Ancestors & Depth

Tip: If you eager load parent.parent..., depth() and ancestors() can walk in memory with 0 queries.

Descendants (CTE fast path + BFS fallback)

These APIs automatically use a recursive CTE when your driver supports it; otherwise they switch to a BFS strategy optimized to minimize data transfer.

Query Scopes

Customization

Change the parent foreign key column (no method override needed)

Or override the methods directly

How it works (short version)

• Depth & Ancestors: walk up using eager-loaded parents when available; otherwise perform tiny per-hop lookups (SELECT pk, parent_fk).

• Descendants:

  • CTE: WITH RECURSIVE to expand the subtree in one query. SQL lives in src/Sql/*.sql and is loaded + templated at runtime.
  • BFS: level-order scan using whereIn(parent_fk, frontier) and pluck(pk) in batches to reduce memory and round-trips.

All traversals include cycle and missing-parent guards.

Performance Notes

• Prefer CTE-capable DBs (MySQL 8+, PostgreSQL, SQLite) to enable single-query descendant expansion.
• When falling back to BFS, tune the chunkSize argument of descendantIds($maxDepth, $chunkSize).
• Eager load parent.parent... for top-down depth/ancestor operations to avoid extra queries.

Testing locally (optional)

This repo includes a minimal Docker + Pest setup for local testing.

If Composer blocks a dev plugin (like Pest), you can allow it:

FAQ

Q: Does this require a full Laravel app? A: No. It only needs Eloquent. Tests use Orchestra Testbench.

Q: Can I customize the SQL? A: Yes. Edit the files in src/Sql/. The trait replaces placeholders and binds parameters positionally.

Q: Do I need to call anything to choose CTE or BFS? A: No. The trait auto-detects driver support and picks the best path.

License

MIT