README

A Laravel package for implementing multi-tree hierarchical structures using the Nested Set Model.

Overview

This package supports Multi-Tree structures (multiple root nodes) and allows movement of nodes between trees. It works with various model primary key types: int, uuid, and ulid.

Key Advantages

• Multi-Tree Support: Manage multiple independent trees within the same table
• Cross-Tree Operations: Move nodes between different trees with ease
• Flexible Primary Keys: Works with various key types including int, uuid, and ulid
• Comprehensive Tree Health Tools: Built-in validation and repair utilities for tree integrity
• Performance Optimized: Efficiently retrieves hierarchical data with minimal database queries
• Modern PHP Support: Utilizes modern PHP 8.x features and strict typing
• Flexible Configuration: Highly customizable attribute naming and behavior
• Well Documented: Complete documentation with practical examples
• Thoroughly Tested: Comprehensive test suite ensuring reliability

What are nested sets?

Nested Set Model is an efficient way to store hierarchical data in relational databases:

The nested set model numbers nodes according to a tree traversal, which visits each node twice, assigning numbers in the order of visiting, and at both visits. This leaves two numbers for each node, which are stored as attributes. Querying becomes inexpensive: hierarchy membership can be tested by comparing these numbers. Updating requires renumbering and is therefore expensive.

Ideal Use Cases

NSM shows good performance when:

• Trees are updated infrequently
• Fast retrieval of related nodes is needed
• Building multi-depth menus or category structures

Visualization

Requirements

• PHP: >= 8.4
• Laravel: >= 13.0

It is highly recommended to use a database that supports transactions (like PostgreSQL) to protect tree structures from corruption.

Installation

composer require efureev/laravel-trees

Documentation

• Basic Usage
• Advanced Tree Configuration
• Database Migration
• Creating Nodes
• Managing Nodes
• Retrieving Nodes
• Model Helpers
• Console Commands
• Health Checks and Fixing

Testing

The test suite runs against PostgreSQL. If you don't have PostgreSQL installed locally, use the bundled Docker setup (PostgreSQL 18):

# Run the whole test suite inside Docker (spins up PostgreSQL 18 automatically)
composer test:docker

Or run the tests directly against an available PostgreSQL instance:

DB_HOST=localhost DB_PORT=5432 DB_DATABASE=forge DB_USERNAME=forge DB_PASSWORD=forge composer test
# or
./vendor/bin/phpunit --testdox