@@ -59,28 +59,40 @@ composer require yii2-extensions/nested-sets-behavior
5959
6060### How it works
6161
62+ The nested sets model is a technique for storing hierarchical data in a relational database. Unlike adjacency lists
63+ (parent_id approach), nested sets enable efficient tree operations with minimal database queries.
64+
62651 . ** Creates root nodes** using the nested sets pattern with ` lft ` , ` rgt ` , and ` depth ` fields.
63662 . ** Manages hierarchy** automatically when inserting, moving, or deleting nodes.
64673 . ** Optimizes queries** using boundary values for efficient tree traversal.
65684 . ** Supports transactions** to ensure data integrity during complex operations.
6669
67- ## Database setup
68-
69- The package includes migrations to create the necessary database tables for nested sets functionality.
70+ #### Why nested sets?
7071
71- ### Available migrations
72+ - ** Fast queries** : Get all descendants with a single query (` lft BETWEEN parent.lft AND parent.rgt ` ).
73+ - ** Efficient tree operations** : No recursive queries needed for tree traversal.
74+ - ** Automatic maintenance** : Left/right boundaries are calculated automatically.
75+ - ** Depth tracking** : Easy to limit query depth or build breadcrumbs.
7276
73- The package provides two migration files.
77+ ``` text
78+ Example tree structure:
79+ Electronics (1,12,0)
80+ ├── Mobile Phones (2,7,1)
81+ │ └── Smartphones (3,6,1)
82+ │ └── iPhone (4,5,2)
83+ └── Computers (8,11,1)
84+ └── Laptops (9,10,2)
7485
75- 1 . ** Single tree migration ** ( ` m250707_103609_tree.php ` ) - for single tree per table.
76- 2 . ** Multiple trees migration ** ( ` m250707_104009_multiple_tree.php ` ) - for multiple independent trees.
86+ Numbers represent: (left, right, depth)
87+ ```
7788
78- ### Using package migrations
89+ ### Database setup
7990
80- #### Method 1: Run migrations directly from extension (Recommended)
91+ The package includes ready-to-use migrations for creating the necessary database structure.
8192
82- Configure your console application to include the extension migrations path.
93+ #### Quick setup (Recommended)
8394
95+ 1 . ** Configure console application** :
8496``` php
8597<?php
8698
@@ -94,45 +106,33 @@ return [
94106 'migrate' => [
95107 'class' => MigrateController::class,
96108 'migrationPath' => [
97- '@console/migrations', // Your app migrations
98- '@vendor/yii2-extensions/nested-sets-behavior/migrations', // Extension migrations
109+ '@console/migrations',
110+ '@vendor/yii2-extensions/nested-sets-behavior/migrations',
99111 ],
100112 ],
101113 ],
102114];
103115```
104116
105- Then run migrations normally.
106-
117+ 2 . ** Run migrations** :
107118``` bash
108- # View available migrations (including extension migrations)
109- ./yii migrate/history
110-
111- # Run all pending migrations
112- ./yii migrate
113-
114- # Or run specific migrations
119+ # For single tree structure
115120./yii migrate/up m250707_103609_tree
121+
122+ # For multiple trees structure
116123./yii migrate/up m250707_104009_multiple_tree
117124```
118125
119- #### Method 2: Using migration path parameter
120-
121- Run migrations directly without configuration changes.
126+ #### Alternative: Direct migration execution
122127
123128``` bash
124- # Run single tree migration
129+ # Run without configuration changes
125130./yii migrate/up --migrationPath=@vendor/yii2-extensions/nested-sets-behavior/migrations
126-
127- # Run specific migration from extension
128- ./yii migrate/up m250707_103609_tree --migrationPath=@vendor/yii2-extensions/nested-sets-behavior/migrations
129131```
130132
131- ### Migration details
133+ #### Table structures created
132134
133- #### Single tree migration (` m250707_103609_tree.php ` )
134-
135- Creates a ` tree ` table with the following structure:
135+ ** Single tree** (` m250707_103609_tree.php ` ). Creates a ` tree ` table for single hierarchical structure.
136136
137137``` sql
138138CREATE TABLE `tree ` (
@@ -149,14 +149,12 @@ CREATE TABLE `tree` (
149149);
150150```
151151
152- #### Multiple tree migration (` m250707_104009_multiple_tree.php ` )
153-
154- Creates a ` multiple_tree ` table with the following structure:
152+ ** Multiple trees** (` m250707_104009_multiple_tree.php ` ). Creates a ` multiple_tree ` table for multiple independent trees.
155153
156154``` sql
157155CREATE TABLE `multiple_tree ` (
158156 ` id` int (11 ) NOT NULL AUTO_INCREMENT,
159- ` tree` int (11 ) DEFAULT NULL ,
157+ ` tree` int (11 ) DEFAULT NULL , -- Tree identifier
160158 ` name` varchar (255 ) NOT NULL ,
161159 ` lft` int (11 ) NOT NULL ,
162160 ` rgt` int (11 ) NOT NULL ,
0 commit comments