Nestedset Laravel Package

Technical Evaluation

This is a hard fork of kalnoy/nestedset — the de facto nested-set implementation for Laravel — rebranded and re-namespaced under the Lunar organisation. The 1.0.0 release is a stabilisation release, not a feature release: namespace rebrand, native type declarations, static analysis, Testbench-based test suite, multi-engine CI, a global-scope hardening fix, and a zero-offset SQL fix.

Architecture fit. Nested sets remain a sound model for read-heavy hierarchies (category trees, menu structures, taxonomy) where depth-first traversal and subtree queries dominate and writes are comparatively rare. That trade-off has not changed. What has changed is ownership: this is now a Lunar-maintained fork, which means the technical evaluation is less about the algorithm and more about the supply-chain and divergence posture of the package.

Integration feasibility. Straightforward within the intended context. The package is a Laravel service provider plus a NodeTrait; adoption is a Composer require, a trait import, and a schema change adding _lft, _rgt, parent_id columns. For a greenfield Laravel 12 project — or anything inside the Lunar commerce stack — this is low-friction. For an existing kalnoy/nestedset consumer it is not drop-in: the namespace rebrand touches every use statement, trait import, config publish tag, and any subclassed node behaviour.

Technical risk. The material risks are:

• Namespace rebrand is a breaking change by definition. Any code, package, or documentation referencing Kalnoy\Nestedset\* must be migrated. A fork that changes the namespace cannot be swapped in behind an existing dependency without edits.
• Native type declarations are a subtle BC break. Adding parameter and return types to trait methods breaks downstream subclasses and overrides that were written against the untyped upstream signatures. This is the kind of break that surfaces at runtime in consumer code, not at install time.
• Global-scope hardening changes query semantics. "Hardening against global scopes" is almost certainly a behavioural change: tree operations that previously inherited or ignored a global scope will now do the other. Consumers with soft deletes, tenancy scopes, or published/active scopes on their node models should assume their results may shift and re-run their tree integrity tests.
• Zero-offset SQL fix is a genuine bug fix, but it changes emitted SQL; anything asserting on query strings or relying on the previous (broken) behaviour will notice.
• Bus factor and fork divergence. A single primary contributor's fork of a widely-used upstream means upstream fixes, CVEs, and Laravel compatibility patches must be manually re-applied. There is no guarantee of parity with kalnoy/nestedset going forward, and no stated upstream-sync policy in the notes.

Key questions for the maintainers. What is the Composer package name and does it replace/provide the upstream package? Is this a permanent fork or a temporary vendored fork pending upstream Laravel 12 support? Is there a written upgrade guide enumerating the namespace and typing breaks, or is the changelog the only migration documentation? Is "Laravel 12/13" a forward-looking compatibility claim (i.e. illuminate/support: ^12|^13 with 13 unverified) or tested support? Does the multi-engine CI actually cover MySQL, Postgres, and SQLite for tree-mutating operations, or only the read paths? What is the security disclosure process?

Integration Approach

Stack fit. Strong fit for Laravel 12+ applications and mandatory-by-default for Lunar commerce projects that depend on it transitively. Poor fit as a replacement for a working kalnoy/nestedset 6.x installation on Laravel 10/11 — the Laravel version floor and the namespace change both point the wrong way for a low-effort migration.

Migration path. Three distinct cases:

1. New adoption. Require the package directly, add the trait, migrate the schema, and pin the constraint. Lowest cost; do this at project inception rather than retrofitting.
2. Existing kalnoy/nestedset consumer on Laravel 12. Evaluate by replacing the Composer requirement, running a repo-wide namespace rewrite, then diffing behaviour. The real work is not the use statements — it is re-validating every query that touches a node model with a global scope, plus any subclass of the trait.
3. Lunar commerce project. Adopt transitively; treat it as an internal dependency and track the Lunar release cadence rather than the package's own.

Compatibility. Verify concretely rather than trusting the summary: confirm the illuminate/* constraint covers your actual Laravel version, confirm PHP version floor, and confirm the NodeTrait API surface against the upstream method list. If the API has silently dropped or renamed methods during modernisation, that is a hidden break the changelog does not call out.

Sequencing. Do not migrate alongside other framework work. Order: (1) pin and install in a branch, (2) namespace rewrite, (3) run existing test suite, (4) add explicit tests for subtree queries under each global scope your node models use, (5) run a tree-integrity check (_lft/_rgt contiguity and depth consistency) against a production-shaped dataset, (6) only then ship. Budget the global-scope revalidation as the largest line item, not the rename.

Operational Impact

Maintenance. Low ongoing effort and low ongoing attention — but that attention must be deliberate. There is no runtime service to operate; the cost is dependency stewardship. Track the fork's releases, and on each one ask whether it has fallen behind upstream kalnoy/nestedset. A fork that drifts silently is a latent risk, not an acute one.

Support. This is the weakest dimension. A single-contributor fork with no stated support commitment means issue turnaround is best-effort. Escalation paths are the Lunar organisation's channels, not a vendor. Teams that need contractual support should not depend on it as a critical-path component without an internal fallback plan (fork it again, or vendor the trait).

Scaling. Nested sets are read-optimised and write-penalised, and nothing in this release changes that. Every insert, move, or delete rewrites _lft/_rgt across a portion of the table. At high write concurrency on deep or wide trees this serialises and will contend on locks. If the workload is write-heavy or the tree is large and mutating frequently, this is the wrong data model regardless of package quality — evaluate materialised paths or closure tables before adopting.

Failure modes. Ranked by likelihood: (1) tree corruption from writes performed outside a transaction or without wrapping in the package's node operations; (2) silent behavioural drift from the global-scope change, producing subtly wrong subtree results rather than errors; (3) subclass breakage from the native type declarations, surfacing as a fatal error on first use of an overridden method; (4) abandonment or drift from upstream, leaving a Laravel compatibility gap. Only (2) and (3) are introduced by this release; (1) and (4) are inherited properties of the dependency.

Ramp-up. Low for developers already familiar with nested sets, and low for anyone who has used kalnoy/nestedset — the API is intentionally similar. The ramp-up cost sits with reviewers and platform owners, who need to understand the fork relationship and the divergence policy before approving it, not with application developers writing queries.