Laravel Trees Laravel Package

Product Decisions This Supports

• Tree-shaped data model selection (build vs. buy). Adopt a proven nested-set implementation for category trees, org charts, menu hierarchies, comment threads, and permission/resource trees instead of hand-rolling adjacency or closure tables. The package now documents when nested sets fit and when a plain parent link is the better shape (docs/Concepts.md), which is exactly the trade-off a PM needs surfaced before committing a schema.
• Data-integrity guarantees as a feature, not an assumption. The health-check suite now covers the three failure modes that silently corrupt trees in production: gaps left by bulk subtree deletes (RangeCheck), a second root (RootCheck), and orphans (MissingParentCheck). This turns "is our production tree intact?" into a runnable audit rather than a manual SQL exercise — useful for on-call runbooks, pre/post-migration verification, and admin-facing data repair tooling.
• Migration and backfill safety. Combined with isDescendantOf() / isDirectChildOf() and parentsByModelId() now working on single trees, this supports bulk hierarchy imports, re-parenting scripts, and one-off data fixes with far less bespoke code to review.
• Roadmap timing for platform upgrades. PHP 8.5 becomes the hard floor and Laravel 13 the supported target. That is a scheduling input for any product on this package: the upgrade is a platform-currency milestone, not an optional nice-to-have.
• Risk reduction on already-shipped features. The list of fixed defects is squarely in the "quietly wrong rather than loudly broken" category — a delete that re-parented the wrong children, a bound shift on the wrong connection, incorrect duplicate/wrong-parent counts that inflated error scores on larger trees. These are bugs that would surface as user-visible hierarchy corruption and expensive data repair, not as a failing test.
• Lower onboarding and maintenance cost. Test coverage going from 198 to 547 tests with full line-and-method coverage of src/, plus a single composer gate command reproducing CI locally, reduces the internal cost of owning this dependency and shortens code review for contributions or forks.
• Ordering correctness in user-facing surfaces. Ancestors and descendants relations now return in tree order on every code path, including eager loading. That removes a class of "the menu renders out of order sometimes" tickets that would otherwise be chased in application code.

Caveat for the decision log: the migration surface is genuinely small — three internal-only signatures, the shape of HealthyChecker's return array, the argument order for the now-static Table::fromQuery(), and one exception import. Everything else is behaviour that was incorrect being corrected. That means the upgrade is cheap in engineering effort and expensive only in platform terms (PHP 8.5 availability).

When to Consider This Package

Consider it when:

• The dominant read pattern is "give me this node's entire subtree" or "give me the path to root" — nested sets answer both in one query, which is the whole point of the scheme.
• The tree needs stable, meaningful ordering (drag-and-drop menus, ordered categories, ranked taxonomies).
• Writes to the hierarchy are comparatively rare relative to reads: content structures, catalogs, navigation, org structure. Re-parenting is possible but costs a bounded-range update.
• You want integrity checking as a first-class operation — audit jobs, migration verification, admin repair screens — rather than something you write yourself.
• You are already on, or can plan to be on, PHP 8.5 and Laravel 13.
• You need scoped or multi-tree support (per-tenant trees, multiple independent hierarchies in one table).

Look elsewhere when:

• Hierarchy edits are the hot path — frequent moves, inserts at arbitrary positions, or collaborative reordering. Nested sets pay for reads with writes; adjacency lists or closure tables are more forgiving.
• The data is a general graph rather than a tree: DAGs, many-to-many parentage, cycles, or nodes that legitimately have multiple parents.
• Tree depth and node count are both very large and bound updates become a contention point under concurrent writes — evaluate locking behaviour against your write concurrency before committing.
• You are pinned to PHP 8.4 or earlier for the foreseeable future, or still on Laravel 12. v7 will not install; this becomes a gating item rather than a preference.
• You need only one or two levels of hierarchy — a parent_id column and a scope is less machinery, and the package's own new documentation says as much.
• You require a vendor with commercial support or an SLA. This is a community package; treat the pinned version and the test suite as your support contract.

Adoption criteria to confirm before committing: PHP 8.5 on the target runtime and CI image, Laravel 13, a write profile that tolerates bounded-range updates, and a plan for running HealthyChecker against existing production data — including the new checks, which will surface gaps and orphans that the previous three-check suite reported as healthy.

How to Pitch It (Stakeholders)

For executives — one paragraph:

This release is a stabilisation milestone for the tree/hierarchy component our catalog, navigation, and permission structures depend on. It fixes a set of subtle data-corruption bugs — incorrect re-parenting on delete, bounds updated on the wrong database connection, integrity checks that miscounted defects — that would otherwise have surfaced as corrupted hierarchies and manual data repair. Test coverage roughly tripled and now exercises every line of the library, so the risk of regressions reaching production is materially lower. The one material cost is platform currency: the library now requires PHP 8.5. There is no functional reason to delay beyond that dependency, and the migration itself is a handful of small, documented edits.

For engineering leads:

The upgrade path is short and documented in MigrationGuide.md. Four things change: three signatures only reachable from inside the package, HealthyChecker::check() now returns six entries instead of three, Table::fromQuery() is static and no longer picks up configuration applied before the call, and one exception import moves from Php\Support to Fureev\Trees\Exceptions\InvalidConfigException (same name, same message — only the use statement changes). Everything else is a correction to behaviour that was wrong: duplicate and wrong-parent checks now count nodes rather than pairs and triples, so a single defect no longer scores higher on a larger tree; ancestors and descendants are ordered on every path including eager loading; shift() moves both bounds in one statement. Contracts\TreeModel now describes every method the traits add, so code typed as Model&TreeModel passes static analysis, and a test fails if the contract and traits drift again. Run composer gate locally — PHPStan, PHPCS and PHPUnit in CI order, or gate:docker if you'd rather not manage the toolchain. Note that the new RangeCheck, RootCheck and MissingParentCheck will flag real defects in existing trees that the old checks passed; plan a health-check run against staging before rollout and treat any findings as genuine data issues, not false positives.

Headline for the roadmap review: low-migration-risk, high-integrity-value release; the only scheduling dependency is PHP 8.5 availability in the runtime and CI image.