Laravel Trees Laravel Package

Technical Evaluation

Architecture fit: The package remains a nested-set implementation for Eloquent trees, not a general graph library. v7 sharpens that positioning: docs/Concepts.md now explains when a nested set is the right shape versus a simpler parent link, and the new RangeCheck, RootCheck, and restored MissingParentCheck make the integrity model concrete. For teams with read-heavy hierarchical data (categories, org units, menus) where subtree queries dominate, the fit is strong. For write-heavy trees or deep, frequently mutated hierarchies, the nested-set write amplification remains the architectural constraint, and nothing in this release changes that.

Integration feasibility: Feasibility is the main issue in v7. The floor is PHP ^8.5 and Laravel 13 — both bleeding edge. Most enterprise estates are on PHP 8.2/8.3 and Laravel 10–12, so this release is effectively greenfield-only until those platforms are upgraded. The breaking surface is deliberately small: three internal-only signatures, HealthyChecker::check() returning six entries instead of three, Table::fromQuery() becoming static and dropping pre-call instance configuration, and one exception import (Fureev\Trees\Exceptions\InvalidConfigException). The rest are fixes to behavior that was wrong. That is a good major-release shape, but the "wrong behavior" being fixed includes tree mutations — delete re-parenting and bound shifts — so integration testing against real tree data is mandatory, not optional.

Technical risk:

• Platform risk (high): PHP 8.5 + Laravel 13 excludes nearly all current production stacks. ^8.5 also caps below PHP 9, which is correct but means another floor review within roughly a year.
• Data-shape risk (medium-high): The delete re-parenting fix changes which children move where. Existing trees mutated under v6 may already be inconsistent; upgrading the code does not repair the data. Budget for an audit-and-repair pass.
• Monitoring/CI risk (medium): HealthyChecker now returns six entries, and three new checks run by default. Trees that previously passed can now fail. Any CI gate, cron health check, or dashboard comparing the array literally or asserting a clean result will start firing.
• Metric drift (medium): DuplicatesCheck and WrongParentCheck now return node counts rather than pair/triple counts. Zero still means healthy, and isBroken() is unaffected — but thresholds and trend lines built on the old numbers are not comparable.
• Query-plan risk (low-medium): ancestors and descendants are now ordered on every path, including eager loads. That is the correct behavior, but it adds ORDER BY to queries that did not have one, which can change plans on large trees.
• Quality signal (positive): 198 → 547 tests, complete method and line coverage of src/, PHPStan and PHPCS enforced in CI, and a single composer gate command. This materially lowers the "unmaintained package" risk that normally dominates a TPM's build-vs-buy call.

Key questions:

1. What is the support policy for v6, and for how long will it receive security and correctness fixes? This determines whether teams can wait for the PHP 8.5 upgrade.
2. Is Laravel 12 support intentionally dropped, or is the Laravel 13 constraint a floor that will be widened?
3. Does the package ship a repair or rebalance path for trees already corrupted by the v6 delete and shift defects, or is that left to the consumer?
4. What is the expected timeline for PHP 8.5 availability in our base images, CI runners, and hosting platform?
5. Are the new RangeCheck/RootCheck/MissingParentCheck results reportable per-node, or only as aggregate counts? That determines whether we can build a remediation queue rather than a red/green alarm.

Integration Approach

Stack fit: Only viable where PHP 8.5 and Laravel 13 are already target-state or planned within the current planning horizon. On PHP 8.4 or below, this release cannot be installed at all — pin v6 and track the platform upgrade as the gating dependency. Treat v7 as the target for new services and as a scheduled migration for existing ones, not as an opportunistic bump.

Migration path:

1. Pin and baseline. Stay on v6 in production; record current HealthyChecker, DuplicatesCheck, and WrongParentCheck outputs across all tree-bearing models as a baseline.
2. Upgrade the platform first. PHP 8.5 runtime images, CI runners, and Laravel 13. Keep this separate from the package bump so failures are attributable.
3. Run v7 in observe mode. Install v7 on a branch, run the full test suite, then run the new health checks against a production data snapshot. Diff the six-entry results against the v6 baseline. This is where pre-existing corruption surfaces.
4. Audit the four breaking surfaces. Grep for: literal comparisons against HealthyChecker::check() arrays, Table::fromQuery() called on an instance with prior configuration, catch blocks importing the Php\Support exception, and any code calling the three internal signatures.
5. Exercise mutations on staging. Run create, move, delete-subtree, and delete-by-query against a realistic tree and compare resulting bounds and parent links against expectations. The delete re-parenting fix is the highest-consequence change in the release.
6. Review query plans. Capture plans for ancestors, descendants, and their eager-loaded variants before and after; confirm the added ordering is index-supported.
7. Adopt the gate. Wire composer gate (PHPStan, PHPCS, PHPUnit) into the pipeline to match upstream CI, so local and remote results agree.

Compatibility: The Contracts\TreeModel expansion is static-analysis-only at runtime — nothing implements or asserts the interface — but code typed as Model&TreeModel will now pass analysis where it previously errored, and drift between contract and traits is now test-enforced. Attribute::make() gaining explicit parameters is source-compatible. isChildOf() is unchanged and retained, which is the right call; adopt isDescendantOf() and isDirectChildOf() in new code to remove the naming ambiguity.

Sequencing: Platform upgrade → package bump on a branch → data audit and repair → observability/metric updates → production cutover. Do not combine the package major with unrelated feature work; the data-repair step needs a clean rollback point.

Operational Impact

Maintenance: The maintenance posture improves markedly. Complete coverage, enforced static analysis and coding standards, a single local gate command, and a Docker-based gate service mean the package is now cheap to validate before adopting a patch. The cost shifts to the consumer side: we own the data audit and any repair tooling.

Support: Upstream support for v6 is the open dependency. If v6 continues to receive fixes, the upgrade can be scheduled against the PHP 8.5 timeline. If not, teams on PHP 8.2–8.4 are stranded on an unpatched tree-mutation library, which is a material risk given that this release fixes silent data corruption.

Scaling: Unchanged in principle — nested sets trade write cost for read efficiency, and the single-statement shift() reduces round-trips on the write path. The new mandatory ORDER BY on both relations is the one scaling consideration: on very wide trees, ensure (tree_id, lft, rgt) indexing supports ordered retrieval so the sort does not spill.

Failure modes:

• Silent corruption carried forward. Existing malformed trees survive the upgrade; only the new checks reveal them. Mitigation: run the checks against production data before cutover, not after.
• Alert fatigue. Three new checks plus changed counts can turn a previously green health job red on day one. Mitigation: stage the rollout, separate "newly detected pre-existing defect" from "newly introduced regression" in reporting.
• Monitoring blind spots from metric drift. Dashboards comparing raw duplicate/wrong-parent counts will show a step change that is a unit change, not a quality change. Mitigation: annotate the change, re-baseline thresholds.
• Rollback asymmetry. Reverting the package does not revert data mutated under v7's corrected delete semantics. Mitigation: snapshot before the first production mutation.
• Platform dead-end. Adopting v7 locks the application to PHP 8.5 and Laravel 13; a downstream library that has not caught up can block unrelated work.

Ramp-up: Low for developers — the concepts doc, the clarified isDescendantOf()/isDirectChildOf() split, and the expanded TreeModel contract all reduce the "read the source to understand the semantics" tax that nested-set packages normally impose. The real ramp-up is on the operations side: whoever owns the health checks needs to understand what a range hole, a second root, and an orphan each mean, and what the remediation is. That is a half-day of onboarding plus a runbook, and it should be written before the first production health report, not after.