Nestedset Laravel Package

Product Decisions This Supports

• Hierarchical data modelling (build vs. buy): Nested sets give O(1) subtree reads and cheap "all descendants/ancestors" queries — the right primitive for category trees, navigation menus, taxonomy/attributes, org charts, and permission hierarchies. This package is the maintenance decision for that layer, not just a utility.
• Platform/upgrade roadmap: The 1.0.0 release targets Laravel 12/13 and ships native types plus static analysis and Testbench coverage. That makes it a viable dependency for a greenfield Laravel 12/13 build and an explicit line item for any upgrade-from-10/11 plan — either adopt the fork or freeze the legacy kalnoy/nestedset and accept a dead-end dependency.
• Multi-tenant and scoped-domain architecture: Hardening tree operations against global scopes and fixing zero-offset SQL directly affects correctness in any app using tenancy (stancl/tenancy, scoped BelongsToTenant models) or soft deletes. If we run multi-tenant category trees, this is a correctness fix, not a nicety — scope leakage across tenants in tree moves is a data-integrity bug we would otherwise have to patch ourselves.
• Vendor/ownership risk assessment: This is a rebranded fork stewarded by Lunar (a commerce vendor) rather than the original upstream. The decision is whether we depend on a single-vendor fork with one active contributor, versus pinning upstream, versus building internal tree logic. Owning a ~2k-line tree library in-house is a real cost; forking behaviour we rely on without upstream alignment is a bigger one.
• Feature feasibility: Menus/categories with drag-and-drop reordering, breadcrumbs, and "move subtree" operations become cheap. Conversely, this signals where not to spend roadmap: no need to spec custom recursion/CTE work for read-heavy trees.
• Commerce and catalogue workstreams: Lunar's sponsorship means the fork is being exercised against catalogue-scale trees, which is mild evidence of production fitness for exactly the kinds of use cases (product categories, nested collections) most of our roadmap touches.

When to Consider This Package

Adopt when:

• The domain is read-heavy hierarchy — many "give me this subtree / these ancestors / this breadcrumb" reads, comparatively few structural writes.
• We are on Laravel 12/13 and want a maintained dependency rather than an unmaintained one; the alternative is pinning an older major and blocking framework upgrades.
• We need multi-tenant or soft-deleted trees and want the global-scope hardening rather than maintaining a private patch.
• We want the Eloquent API surface (children(), descendants(), ancestors(), toTree(), appendToNode(), move operations) rather than hand-rolled recursive queries.
• The team is small and we would rather rent this than own it — a well-scoped tree library is exactly the kind of dependency that should not be bespoke.

Look elsewhere or build in-house when:

• The tree is write-heavy or edited concurrently at volume. Nested sets rewrite the whole right-hand boundary on every insert/move; that is a lock and write-amplification problem no library fixes. Prefer adjacency list + recursive CTE, materialised path, or a closure table if structural writes dominate.
• We need partial/async tree loads at scale or graph (DAG) semantics — multiple parents, cycles, cross-links. Nested sets model a strict tree only.
• Fork governance is unacceptable to the org. There is one named contributor and no visible corporate SLA; the fork could stall. If the dependency is load-bearing, either accept that and pin, or budget the internal fork-maintenance cost up front.
• We are not on Laravel, or are on a version the fork does not target — verify the constraint before designing around it.
• Existing data is already adjacency-list and volumes are modest; a recursive CTE or simple parent_id recursion may be simpler and cheaper than a schema migration plus package.

How to Pitch It (Stakeholders)

For executives: We evaluated the nested-set package that underpins all tree-shaped data in the product — category trees, menus, taxonomies, org hierarchies. Version 1.0.0 is a modernised fork maintained by Lunar, a commerce vendor using it in production. It brings us onto current Laravel (12/13), adds static analysis and a real test harness, and — most importantly for us — fixes correctness bugs around tenant-scoped trees and zero-offset edge cases that would otherwise become our own incident and patch burden. Recommendation: adopt it as our standard tree layer and treat it as a maintained dependency with a single-vendor risk we accept and monitor. Cost is effectively zero against a quarter of engineering time to reproduce equivalent behaviour; the residual risk is maintainer concentration, which we mitigate by pinning versions and keeping our usage inside the documented API.

For engineering: This is a rebrand of kalnoy/nestedset for Lunar, brought to 1.0.0 with native types, multi-engine CI, static analysis, and Testbench — so it is testable and safe to upgrade. The substantive change is hardening of tree operations against global scopes plus a zero-offset SQL fix; if you run tenanted or soft-deleted trees, that is your motivation right there. Two constraints to design around: nested sets are read-optimised and write-amplified — every insert and move rewrites boundaries, so do not put high-frequency reordering behind it without locking discipline; and this is a single-maintainer fork, so stay on the public API, avoid monkey-patching internals, and pin the version. Validate against our largest tree in staging before committing to the schema change.