# NestedSetsBehavior

> Manages hierarchical data in yii\db\ActiveRecord models using the nested sets pattern.

[API reference](/docs/api/index.md) › [Nested sets behavior](/docs/extensions/nested-sets-behavior/reference/index.md) › NestedSetsBehavior

| class | `yii2\extensions\nestedsets\NestedSetsBehavior` |
| --- | --- |
| Extends | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) » [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| Implements | [`yii\base\Configurable`](/docs/api/yii/base/configurable/index.md) |
| Source | [`src/NestedSetsBehavior.php`](https://github.com/yii2-extensions/nested-sets-behavior/blob/main/src/NestedSetsBehavior.php#L34) |

Manages hierarchical data in [`ActiveRecord`](/docs/api/yii/db/activerecord/index.md) models using the nested sets pattern.

Maintains the left, right and depth attributes of each node and, when [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is set, a tree identifier
that stores several trees in one table. Structural writes serialize on a per-table writer lock held until the
outermost transaction ends, so the connection must enable savepoints and the `nested_sets_lock` registry table must
exist. A plain `delete()` acquires that lock in [`beforeDelete()`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#method-beforeDelete) and therefore requires an active Yii
transaction, for example through [`ActiveRecord::transactions()`](/docs/api/yii/db/activerecord/index.md#method-transactions).

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-depth"></span>`$depth` | `int` |  | `NestedSetsBehavior` |
| <span id="property-depthAttribute"></span>`$depthAttribute` | `"depth"` | Attribute name. Default: `'depth'`. | `NestedSetsBehavior` |
| <span id="property-leftAttribute"></span>`$leftAttribute` | `"lft"` | Attribute name. Default: `'lft'`. | `NestedSetsBehavior` |
| <span id="property-lft"></span>`$lft` | `int` |  | `NestedSetsBehavior` |
| <span id="property-lockTimeout"></span>`$lockTimeout` | `int` | Maximum wait in seconds for each guard-row acquisition; valid range is 1 through 3600. Default: `10`. | `NestedSetsBehavior` |
| <span id="property-owner"></span>[`$owner`](/docs/api/yii/base/behavior/index.md#property-owner) | `yii\base\T\|null` | The owner of this behavior Default: `null`. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| <span id="property-rgt"></span>`$rgt` | `int` |  | `NestedSetsBehavior` |
| <span id="property-rightAttribute"></span>`$rightAttribute` | `"rgt"` | Attribute name. Default: `'rgt'`. | `NestedSetsBehavior` |
| <span id="property-treeAttribute"></span>`$treeAttribute` | `string\|false` | Name of the attribute that stores the tree identifier, or `false` to keep a single tree per table. Default: `false`. | `NestedSetsBehavior` |
| <span id="property-depthValue"></span>`$depthValue` protected | `int\|null` | Cached depth of the owner, or `null` when it must be read from the owner attributes. Default: `null`. | `NestedSetsBehavior` |
| <span id="property-leftValue"></span>`$leftValue` protected | `int\|null` | Cached left value of the owner, or `null` when it must be read from the owner attributes. Default: `null`. | `NestedSetsBehavior` |
| <span id="property-node"></span>`$node` protected | [`yii\db\ActiveRecord`](/docs/api/yii/db/activerecord/index.md)`<yii2\extensions\nestedsets\T>\|null` | Target node of the pending operation, or `null` when the operation has no target. Default: `null`. | `NestedSetsBehavior` |
| <span id="property-operation"></span>`$operation` protected | `string\|null` | Pending operation, one of the `OPERATION_*` constants, or `null` when no structural operation is pending. Default: `null`. | `NestedSetsBehavior` |
| <span id="property-rightValue"></span>`$rightValue` protected | `int\|null` | Cached right value of the owner, or `null` when it must be read from the owner attributes. Default: `null`. | `NestedSetsBehavior` |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-__construct"></span>[`__construct()`](/docs/api/yii/base/baseobject/index.md#method-__construct) | Constructor. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__call"></span>[`__call()`](/docs/api/yii/base/baseobject/index.md#method-__call) | Calls the named method which is not a class method. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__get"></span>[`__get()`](/docs/api/yii/base/baseobject/index.md#method-__get) | Returns the value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__isset"></span>[`__isset()`](/docs/api/yii/base/baseobject/index.md#method-__isset) | Checks if a property is set, i.e. defined and not null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__set"></span>[`__set()`](/docs/api/yii/base/baseobject/index.md#method-__set) | Sets value of an object property. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-__unset"></span>[`__unset()`](/docs/api/yii/base/baseobject/index.md#method-__unset) | Sets an object property to null. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`acquireTreeLock()`](#method-acquireTreeLock) | Acquires the table writer lock before application reads or raw SQL in an existing Yii transaction. | `NestedSetsBehavior` |
| [`afterDelete()`](#method-afterDelete) | Closes the gap left by the deleted owner, moving the children of a node deleted on its own one level up. | `NestedSetsBehavior` |
| [`afterInsert()`](#method-afterInsert) | Assigns the primary key of a new root as its tree identifier when [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is enabled. | `NestedSetsBehavior` |
| [`afterRefresh()`](#method-afterRefresh) | Clears cached coordinates after a model refresh without cancelling an active operation. | `NestedSetsBehavior` |
| [`afterUpdate()`](#method-afterUpdate) | Moves the owner subtree to the position requested by the pending operation and reloads the owner coordinates. | `NestedSetsBehavior` |
| [`appendTo()`](#method-appendTo) | Appends the owner as the last child of the target node, inserting a new owner or moving an existing subtree. | `NestedSetsBehavior` |
| <span id="method-attach"></span>[`attach()`](/docs/api/yii/base/behavior/index.md#method-attach) | Attaches the behavior object to the component. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| [`beforeDelete()`](#method-beforeDelete) | Acquires the table writer lock, reloads the owner coordinates, and rejects deleting a root node on its own. | `NestedSetsBehavior` |
| [`beforeInsert()`](#method-beforeInsert) | Reloads the target coordinates and assigns the coordinates of the new owner according to the pending operation. | `NestedSetsBehavior` |
| [`beforeUpdate()`](#method-beforeUpdate) | Reloads the coordinates of the owner and the target and validates the pending move before the owner is updated. | `NestedSetsBehavior` |
| <span id="method-canGetProperty"></span>[`canGetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canGetProperty) | Returns a value indicating whether a property can be read. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-canSetProperty"></span>[`canSetProperty()`](/docs/api/yii/base/baseobject/index.md#method-canSetProperty) | Returns a value indicating whether a property can be set. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`children()`](#method-children) | Returns a query for the descendants of the owner, ordered by left value and optionally limited in depth. | `NestedSetsBehavior` |
| <span id="method-className"></span>[`className()`](/docs/api/yii/base/baseobject/index.md#method-className) static | Returns the fully qualified name of this class. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`deleteWithChildren()`](#method-deleteWithChildren) | Deletes the owner together with all its descendants. | `NestedSetsBehavior` |
| <span id="method-detach"></span>[`detach()`](/docs/api/yii/base/behavior/index.md#method-detach) | Detaches the behavior object from the component. | [`yii\base\Behavior`](/docs/api/yii/base/behavior/index.md) |
| [`events()`](#method-events) | Returns the [`ActiveRecord`](/docs/api/yii/db/activerecord/index.md) lifecycle event handlers of the behavior. | `NestedSetsBehavior` |
| <span id="method-hasMethod"></span>[`hasMethod()`](/docs/api/yii/base/baseobject/index.md#method-hasMethod) | Returns a value indicating whether a method is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-hasProperty"></span>[`hasProperty()`](/docs/api/yii/base/baseobject/index.md#method-hasProperty) | Returns a value indicating whether a property is defined. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| <span id="method-init"></span>[`init()`](/docs/api/yii/base/baseobject/index.md#method-init) | Initializes the object. | [`yii\base\BaseObject`](/docs/api/yii/base/baseobject/index.md) |
| [`insertAfter()`](#method-insertAfter) | Places the owner as the next sibling of the target node, inserting a new owner or moving an existing subtree. | `NestedSetsBehavior` |
| [`insertBefore()`](#method-insertBefore) | Places the owner as the previous sibling of the target node, inserting a new owner or moving an existing subtree. | `NestedSetsBehavior` |
| [`invalidateCache()`](#method-invalidateCache) | Clears the cached coordinates and discards the pending operation and target node. | `NestedSetsBehavior` |
| [`isChildOf()`](#method-isChildOf) | Returns whether the owner is a descendant of the given node within the same tree. | `NestedSetsBehavior` |
| [`isLeaf()`](#method-isLeaf) | Returns whether the owner has no descendants. | `NestedSetsBehavior` |
| [`isRoot()`](#method-isRoot) | Returns whether the owner is a root node. | `NestedSetsBehavior` |
| [`leaves()`](#method-leaves) | Returns a query for the leaf descendants of the owner, ordered by left value. | `NestedSetsBehavior` |
| [`makeRoot()`](#method-makeRoot) | Makes the owner a root, starting a new tree for a new owner or promoting an existing subtree to a new tree. | `NestedSetsBehavior` |
| [`next()`](#method-next) | Returns a query for the next sibling of the owner. | `NestedSetsBehavior` |
| [`parents()`](#method-parents) | Returns a query for the ancestors of the owner, ordered by left value and optionally limited in depth. | `NestedSetsBehavior` |
| [`prependTo()`](#method-prependTo) | Prepends the owner as the first child of the target node, inserting a new owner or moving an existing subtree. | `NestedSetsBehavior` |
| [`prev()`](#method-prev) | Returns a query for the previous sibling of the owner. | `NestedSetsBehavior` |
| [`beforeInsertNode()`](#method-beforeInsertNode) protected | Assigns the coordinates of a new child or sibling at the given position and opens space for it in the tree. | `NestedSetsBehavior` |
| [`beforeInsertRootNode()`](#method-beforeInsertRootNode) protected | Assigns root coordinates to a new owner. | `NestedSetsBehavior` |
| [`moveNode()`](#method-moveNode) protected | Moves the owner subtree to the position described by the context, within its tree or into another tree. | `NestedSetsBehavior` |
| [`moveNodeAsRoot()`](#method-moveNodeAsRoot) protected | Promotes the owner subtree to a new tree identified by the owner primary key and closes the gap it leaves. | `NestedSetsBehavior` |
| [`shiftLeftRightAttribute()`](#method-shiftLeftRightAttribute) protected | Adds the delta to every left and right value greater than or equal to the given value within the owner tree. | `NestedSetsBehavior` |

## Constants

| Constant | Value | Description | Defined by |
| --- | --- | --- | --- |
| <span id="const-OPERATION_APPEND_TO"></span>`OPERATION_APPEND_TO` | `'appendTo'` | Identifies the operation that places the owner as the last child of a target node. | `NestedSetsBehavior` |
| <span id="const-OPERATION_DELETE_WITH_CHILDREN"></span>`OPERATION_DELETE_WITH_CHILDREN` | `'deleteWithChildren'` | Identifies the operation that deletes the owner together with all its descendants. | `NestedSetsBehavior` |
| <span id="const-OPERATION_INSERT_AFTER"></span>`OPERATION_INSERT_AFTER` | `'insertAfter'` | Identifies the operation that places the owner as the next sibling of a target node. | `NestedSetsBehavior` |
| <span id="const-OPERATION_INSERT_BEFORE"></span>`OPERATION_INSERT_BEFORE` | `'insertBefore'` | Identifies the operation that places the owner as the previous sibling of a target node. | `NestedSetsBehavior` |
| <span id="const-OPERATION_MAKE_ROOT"></span>`OPERATION_MAKE_ROOT` | `'makeRoot'` | Identifies the operation that creates the owner as a root or promotes it to the root of a new tree. | `NestedSetsBehavior` |
| <span id="const-OPERATION_PREPEND_TO"></span>`OPERATION_PREPEND_TO` | `'prependTo'` | Identifies the operation that places the owner as the first child of a target node. | `NestedSetsBehavior` |

## Method details

### acquireTreeLock() <span id="method-acquireTreeLock"></span>

```php
public function acquireTreeLock(): void
```

Acquires the table writer lock before application reads or raw SQL in an existing Yii transaction.

The database retains the lock until that transaction commits or rolls back.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if no Yii transaction is active, savepoints are disabled, [`$lockTimeout`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-lockTimeout) is out of range, the `nested_sets_lock` registry is missing, or the lock wait times out.

### afterDelete() <span id="method-afterDelete"></span>

```php
public function afterDelete(): void
```

Closes the gap left by the deleted owner, moving the children of a node deleted on its own one level up.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if updating the remaining coordinates fails.

### afterInsert() <span id="method-afterInsert"></span>

```php
public function afterInsert(): void
```

Assigns the primary key of a new root as its tree identifier when [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is enabled.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if the owner model has no primary key or the tree identifier update fails.

### afterRefresh() <span id="method-afterRefresh"></span>

```php
public function afterRefresh(): void
```

Clears cached coordinates after a model refresh without cancelling an active operation.

### afterUpdate() <span id="method-afterUpdate"></span>

```php
public function afterUpdate(): void
```

Moves the owner subtree to the position requested by the pending operation and reloads the owner coordinates.

**Throws**

- [`RuntimeException`](https://www.php.net/manual/en/class.runtimeexception.php): if the pending operation does not move the owner relative to a target node.
- [`yii\db\StaleObjectException`](/docs/api/yii/db/staleobjectexception/index.md): if the owner no longer exists when its coordinates are reloaded.

### appendTo() <span id="method-appendTo"></span>

```php
public function appendTo(yii2\extensions\nestedsets\T $node, bool $runValidation = true, list<string>|null $attributes = null): bool
```

Appends the owner as the last child of the target node, inserting a new owner or moving an existing subtree.

Runs in its own transaction, acquires the table writer lock, rolls back and restores the owner on failure, and
reloads the coordinates of the owner and the target on success.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$node` | `yii2\extensions\nestedsets\T` | Node that becomes the parent of the owner. |
| `$runValidation` | `bool` | Whether to validate the owner before saving. |
| `$attributes` | `list<string>\|null` | Attributes to save, or `null` to save all attributes. |

**Returns**

`bool`: Whether the owner was saved.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### beforeDelete() <span id="method-beforeDelete"></span>

```php
public function beforeDelete(): void
```

Acquires the table writer lock, reloads the owner coordinates, and rejects deleting a root node on its own.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if the owner is a new record.
- [`yii\base\NotSupportedException`](/docs/api/yii/base/notsupportedexception/index.md): if the owner is a root and the deletion is not run by [`deleteWithChildren()`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#method-deleteWithChildren).
- [`yii\db\StaleObjectException`](/docs/api/yii/db/staleobjectexception/index.md): if the owner no longer exists or its optimistic lock version has changed.
- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if the writer lock cannot be acquired, for example without an active Yii transaction.

### beforeInsert() <span id="method-beforeInsert"></span>

```php
public function beforeInsert(): void
```

Reloads the target coordinates and assigns the coordinates of the new owner according to the pending operation.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if the target node is a new record or uses another connection or table, if a sibling of a root is requested, or if a second root is created while [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is `false`.
- [`yii\base\NotSupportedException`](/docs/api/yii/base/notsupportedexception/index.md): if no supported operation is pending, for example on a plain `insert()`.
- [`yii\db\StaleObjectException`](/docs/api/yii/db/staleobjectexception/index.md): if the target node no longer exists.

### beforeUpdate() <span id="method-beforeUpdate"></span>

```php
public function beforeUpdate(): void
```

Reloads the coordinates of the owner and the target and validates the pending move before the owner is updated.

For structural moves, also marks the optimistic lock attribute dirty so that the update checks and increments it.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if the move is invalid: promoting a root, making a root while [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is `false`, or targeting a new record, the owner itself, one of its descendants, or a root for sibling moves.
- [`yii\db\StaleObjectException`](/docs/api/yii/db/staleobjectexception/index.md): if the owner or the target no longer exists, or the owner optimistic lock version has changed.

### children() <span id="method-children"></span>

```php
public function children(int|null $depth = null): yii\db\ActiveQuery<yii2\extensions\nestedsets\T>
```

Returns a query for the descendants of the owner, ordered by left value and optionally limited in depth.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$depth` | `int\|null` | Maximum number of levels below the owner, or `null` for all descendants. |

**Returns**

[`yii\db\ActiveQuery`](/docs/api/yii/db/activequery/index.md)`<yii2\extensions\nestedsets\T>`: Query for the descendants of the owner.

### deleteWithChildren() <span id="method-deleteWithChildren"></span>

```php
public function deleteWithChildren(): bool|int
```

Deletes the owner together with all its descendants.

Runs in its own transaction regardless of the model `transactions()` configuration, acquires the table writer
lock, reloads the owner coordinates before deleting, and rolls back and restores the owner on failure.

**Returns**

`bool|int`: Number of deleted rows, or `false` if [`ActiveRecord::beforeDelete()`](/docs/api/yii/db/baseactiverecord/index.md#method-beforeDelete) cancels the deletion.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### events() <span id="method-events"></span>

```php
public function events(): string[]
```

Returns the [`ActiveRecord`](/docs/api/yii/db/activerecord/index.md) lifecycle event handlers of the behavior.

**Returns**

`string[]`: The event handlers of the behavior.

### insertAfter() <span id="method-insertAfter"></span>

```php
public function insertAfter(yii\db\ActiveRecord $node, bool $runValidation = true, list<string>|null $attributes = null): bool
```

Places the owner as the next sibling of the target node, inserting a new owner or moving an existing subtree.

Runs in its own transaction, acquires the table writer lock, rolls back and restores the owner on failure, and
reloads the coordinates of the owner and the target on success.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$node` | [`yii\db\ActiveRecord`](/docs/api/yii/db/activerecord/index.md) | Node that becomes the previous sibling of the owner. |
| `$runValidation` | `bool` | Whether to validate the owner before saving. |
| `$attributes` | `list<string>\|null` | Attributes to save, or `null` to save all attributes. |

**Returns**

`bool`: Whether the owner was saved.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### insertBefore() <span id="method-insertBefore"></span>

```php
public function insertBefore(yii\db\ActiveRecord $node, bool $runValidation = true, list<string>|null $attributes = null): bool
```

Places the owner as the previous sibling of the target node, inserting a new owner or moving an existing subtree.

Runs in its own transaction, acquires the table writer lock, rolls back and restores the owner on failure, and
reloads the coordinates of the owner and the target on success.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$node` | [`yii\db\ActiveRecord`](/docs/api/yii/db/activerecord/index.md) | Node that becomes the next sibling of the owner. |
| `$runValidation` | `bool` | Whether to validate the owner before saving. |
| `$attributes` | `list<string>\|null` | Attributes to save, or `null` to save all attributes. |

**Returns**

`bool`: Whether the owner was saved.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### invalidateCache() <span id="method-invalidateCache"></span>

```php
public function invalidateCache(): void
```

Clears the cached coordinates and discards the pending operation and target node.

### isChildOf() <span id="method-isChildOf"></span>

```php
public function isChildOf(yii\db\ActiveRecord $node): bool
```

Returns whether the owner is a descendant of the given node within the same tree.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$node` | [`yii\db\ActiveRecord`](/docs/api/yii/db/activerecord/index.md) | Candidate ancestor of the owner. |

**Returns**

`bool`: Whether the owner lies strictly inside the boundaries of the node and shares its tree identifier.

### isLeaf() <span id="method-isLeaf"></span>

```php
public function isLeaf(): bool
```

Returns whether the owner has no descendants.

**Returns**

`bool`: Whether the right value of the owner exceeds its left value by exactly `1`.

### isRoot() <span id="method-isRoot"></span>

```php
public function isRoot(): bool
```

Returns whether the owner is a root node.

**Returns**

`bool`: Whether the left value of the owner is `1`.

### leaves() <span id="method-leaves"></span>

```php
public function leaves(): yii\db\ActiveQuery<yii2\extensions\nestedsets\T>
```

Returns a query for the leaf descendants of the owner, ordered by left value.

**Returns**

[`yii\db\ActiveQuery`](/docs/api/yii/db/activequery/index.md)`<yii2\extensions\nestedsets\T>`: Query for the descendants of the owner that have no children.

### makeRoot() <span id="method-makeRoot"></span>

```php
public function makeRoot(bool $runValidation = true, list<string>|null $attributes = null): bool
```

Makes the owner a root, starting a new tree for a new owner or promoting an existing subtree to a new tree.

Runs in its own transaction, acquires the table writer lock, rolls back and restores the owner on failure, and
reloads the owner coordinates on success. Promoting an existing node requires [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute).

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$runValidation` | `bool` | Whether to validate the owner before saving. |
| `$attributes` | `list<string>\|null` | Attributes to save, or `null` to save all attributes. |

**Returns**

`bool`: Whether the owner was saved.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### next() <span id="method-next"></span>

```php
public function next(): yii\db\ActiveQuery<yii2\extensions\nestedsets\T>
```

Returns a query for the next sibling of the owner.

**Returns**

[`yii\db\ActiveQuery`](/docs/api/yii/db/activequery/index.md)`<yii2\extensions\nestedsets\T>`: Query for the node whose left value follows the right value of the owner; empty when there is none.

### parents() <span id="method-parents"></span>

```php
public function parents(int|null $depth = null): yii\db\ActiveQuery<yii2\extensions\nestedsets\T>
```

Returns a query for the ancestors of the owner, ordered by left value and optionally limited in depth.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$depth` | `int\|null` | Maximum number of levels above the owner, or `null` for all ancestors. |

**Returns**

[`yii\db\ActiveQuery`](/docs/api/yii/db/activequery/index.md)`<yii2\extensions\nestedsets\T>`: Query for the ancestors of the owner.

### prependTo() <span id="method-prependTo"></span>

```php
public function prependTo(yii\db\ActiveRecord $node, bool $runValidation = true, list<string>|null $attributes = null): bool
```

Prepends the owner as the first child of the target node, inserting a new owner or moving an existing subtree.

Runs in its own transaction, acquires the table writer lock, rolls back and restores the owner on failure, and
reloads the coordinates of the owner and the target on success.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$node` | [`yii\db\ActiveRecord`](/docs/api/yii/db/activerecord/index.md) | Node that becomes the parent of the owner. |
| `$runValidation` | `bool` | Whether to validate the owner before saving. |
| `$attributes` | `list<string>\|null` | Attributes to save, or `null` to save all attributes. |

**Returns**

`bool`: Whether the owner was saved.

**Throws**

- [`Throwable`](https://www.php.net/manual/en/class.throwable.php): if a lifecycle handler or database operation fails.

### prev() <span id="method-prev"></span>

```php
public function prev(): yii\db\ActiveQuery<yii2\extensions\nestedsets\T>
```

Returns a query for the previous sibling of the owner.

**Returns**

[`yii\db\ActiveQuery`](/docs/api/yii/db/activequery/index.md)`<yii2\extensions\nestedsets\T>`: Query for the node whose right value precedes the left value of the owner; empty when there is none.

### beforeInsertNode() <span id="method-beforeInsertNode"></span>

```php
protected function beforeInsertNode(int $value, int $depth): void
```

Assigns the coordinates of a new child or sibling at the given position and opens space for it in the tree.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `int` | Left value of the new node. |
| `$depth` | `int` | Depth offset relative to the target node: `0` for a sibling, `1` for a child. |

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if a sibling of a root node is requested.

### beforeInsertRootNode() <span id="method-beforeInsertRootNode"></span>

```php
protected function beforeInsertRootNode(): void
```

Assigns root coordinates to a new owner.

**Throws**

- [`yii\db\Exception`](/docs/api/yii/db/exception/index.md): if [`$treeAttribute`](/docs/extensions/nested-sets-behavior/reference/nestedsetsbehavior/index.md#property-treeAttribute) is `false` and the table already contains a node.

### moveNode() <span id="method-moveNode"></span>

```php
protected function moveNode(yii2\extensions\nestedsets\NodeContext $context): void
```

Moves the owner subtree to the position described by the context, within its tree or into another tree.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$context` | [`NodeContext`](/docs/extensions/nested-sets-behavior/reference/nodecontext/index.md) | Target position and depth offset of the move. |

### moveNodeAsRoot() <span id="method-moveNodeAsRoot"></span>

```php
protected function moveNodeAsRoot(mixed $treeValue): void
```

Promotes the owner subtree to a new tree identified by the owner primary key and closes the gap it leaves.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$treeValue` | `mixed` | Identifier of the tree that currently contains the subtree. |

### shiftLeftRightAttribute() <span id="method-shiftLeftRightAttribute"></span>

```php
protected function shiftLeftRightAttribute(int $value, int $delta): void
```

Adds the delta to every left and right value greater than or equal to the given value within the owner tree.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `int` | Lowest boundary value to shift, inclusive. |
| `$delta` | `int` | Signed offset to add; a negative value closes a gap. |