Skip to content

Commit 4033556

Browse files
committed
docs: enhance README.md with detailed explanation of nested sets model and migration setup instructions.
1 parent 0fafbe5 commit 4033556

File tree

1 file changed

+34
-36
lines changed

1 file changed

+34
-36
lines changed

README.md

Lines changed: 34 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
6265
1. **Creates root nodes** using the nested sets pattern with `lft`, `rgt`, and `depth` fields.
6366
2. **Manages hierarchy** automatically when inserting, moving, or deleting nodes.
6467
3. **Optimizes queries** using boundary values for efficient tree traversal.
6568
4. **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
138138
CREATE 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
157155
CREATE 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

Comments
 (0)