Nested sets behavior

A powerful behavior for managing hierarchical data structures using the nested sets pattern in Yii ActiveRecord models.

Efficiently store and query tree structures like categories, menus, organizational charts, and any hierarchical data with high-performance database operations.

Features

• ✅ Efficient Tree Operations - Insert, move, delete nodes with automatic boundary management.
• ✅ Flexible Queries - Find ancestors, descendants, siblings, leaves, and roots.
• ✅ Multiple Trees Support - Manage multiple independent trees in the same table.
• ✅ Query Optimization - Single-query operations for maximum performance.
• ✅ Transaction Safety - All operations are wrapped in database transactions.
• ✅ Validation & Error Handling - Comprehensive validation with clear error messages.

Quick start

Installation

composer require yii2-extensions/nested-sets-behavior

How it works

1. Creates root nodes using the nested sets pattern with lft, rgt, and depth fields.
2. Manages hierarchy automatically when inserting, moving, or deleting nodes.
3. Optimizes queries using boundary values for efficient tree traversal.
4. Supports transactions to ensure data integrity during complex operations.

Basic Configuration

Add the behavior to your ActiveRecord model.

<?php

declare(strict_types=1);

use yii\db\ActiveRecord;
use yii2\extensions\nestedsets\NestedSetsBehavior;

/**
 * @phpstan-property int $depth
 * @phpstan-property int $id
 * @phpstan-property int $lft
 * @phpstan-property int $rgt
 */
class Category extends ActiveRecord
{
    public static function tableName(): string
    {
        return '{{%category}}';
    }

    public function behaviors(): array
    {
        return [
            'nestedSets' => [
                'class' => NestedSetsBehavior::class,
                // 'treeAttribute' => 'tree', // Enable for multiple trees
                // 'leftAttribute' => 'lft',   // Default: 'lft'
                // 'rightAttribute' => 'rgt',  // Default: 'rgt'
                // 'depthAttribute' => 'depth', // Default: 'depth'
            ],
        ];
    }

    public function transactions(): array
    {
        return [
            self::SCENARIO_DEFAULT => self::OP_ALL,
        ];
    }
}

Database schema

Create the required database fields.

-- Single tree structure
CREATE TABLE category (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255) NOT NULL,
    lft INT NOT NULL,
    rgt INT NOT NULL,
    depth INT NOT NULL
);

-- Multiple trees structure
CREATE TABLE category (
    id INT PRIMARY KEY AUTO_INCREMENT,
    tree INT,
    name VARCHAR(255) NOT NULL,
    lft INT NOT NULL,
    rgt INT NOT NULL,
    depth INT NOT NULL
);

Basic Usage

Creating and building trees

<?php

declare(strict_types=1);

// Create root node
$root = new Category(['name' => 'Electronics']);
$root->makeRoot();

// Add children
$phones = new Category(['name' => 'Mobile Phones']);
$phones->appendTo($root);

$computers = new Category(['name' => 'Computers']);
$computers->appendTo($root);

// Add grandchildren
$smartphone = new Category(['name' => 'Smartphones']);
$smartphone->appendTo($phones);

$laptop = new Category(['name' => 'Laptops']);
$laptop->appendTo($computers);

Querying the tree

<?php

declare(strict_types=1);

// Get all descendants of a node
$children = $root->children()->all();

// Get only direct children
$directChildren = $root->children(1)->all();

// Get all ancestors of a node
$parents = $smartphone->parents()->all();

// Get all leaf nodes (nodes without children)
$leaves = $root->leaves()->all();

// Navigate siblings
$nextSibling = $phones->next()->one();
$prevSibling = $computers->prev()->one();

Moving nodes

<?php

declare(strict_types=1);

// Move as last child
$smartphone->appendTo($computers);

// Move as first child  
$smartphone->prependTo($phones);

// Move as next sibling
$smartphone->insertAfter($laptop);

// Move as previous sibling
$smartphone->insertBefore($laptop);

// Make node a new root (multiple trees only)
$smartphone->makeRoot();

Deleting nodes

<?php

declare(strict_types=1);

// Delete node only (children become children of parent)
$phones->delete();

// Delete node with all descendants
$phones->deleteWithChildren();

Query builder integration

Add query behavior for advanced tree queries.

<?php

declare(strict_types=1);

use yii\db\ActiveQuery;
use yii2\extensions\nestedsets\NestedSetsQueryBehavior;

/**
 * @template T of Category
 *
 * @extends ActiveQuery<T>
 */
class CategoryQuery extends ActiveQuery
{
    public function behaviors(): array
    {
        return [
            'nestedSetsQuery' => NestedSetsQueryBehavior::class,
        ];
    }
}

// In your Category model
/**
 * @phpstan-return CategoryQuery<static>
 */
public static function find(): CategoryQuery
{
    return new CategoryQuery(static::class);
}

Now you can use enhanced queries.

<?php

declare(strict_types=1);

// Find all root nodes
$roots = Category::find()->roots()->all();

// Find all leaf nodes  
$leaves = Category::find()->leaves()->all();

Documentation

For detailed configuration options and advanced usage.

• 📚 Installation Guide
• ⚙️ Configuration Reference
• 💡 Usage Examples
• 🧪 Testing Guide

Quality code

Our social networks

License

Fork

This package is a fork of https://github.com/creocoder/yii2-nested-sets with some corrections.