# QueryConditionBuilder

> Builds Yii condition arrays and offset expressions for nested set queries and bulk coordinate updates.

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

| final class | `yii2\extensions\nestedsets\QueryConditionBuilder` |
| --- | --- |
| Source | [`src/QueryConditionBuilder.php`](https://github.com/yii2-extensions/nested-sets-behavior/blob/main/src/QueryConditionBuilder.php#L14) |

Builds Yii condition arrays and offset expressions for nested set queries and bulk coordinate updates.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`createChildrenCondition()`](#method-createChildrenCondition) static | Returns a condition matching the descendants of a node, optionally limited to a maximum depth below it. | `QueryConditionBuilder` |
| [`createCrossTreeMoveCondition()`](#method-createCrossTreeMoveCondition) static | Returns a condition matching the nodes of a tree whose boundary value is at least the given value. | `QueryConditionBuilder` |
| [`createLeavesCondition()`](#method-createLeavesCondition) static | Returns a condition matching the leaf nodes strictly inside the given ancestor boundaries. | `QueryConditionBuilder` |
| [`createNextSiblingCondition()`](#method-createNextSiblingCondition) static | Returns a condition matching the node whose left value immediately follows the given right value. | `QueryConditionBuilder` |
| [`createOffsetUpdates()`](#method-createOffsetUpdates) static | Returns column expressions for `updateAll()` that add a signed offset to each given attribute. | `QueryConditionBuilder` |
| [`createParentsCondition()`](#method-createParentsCondition) static | Returns a condition matching the ancestors of a node, optionally limited to a maximum number of levels above it. | `QueryConditionBuilder` |
| [`createPrevSiblingCondition()`](#method-createPrevSiblingCondition) static | Returns a condition matching the node whose right value immediately precedes the given left value. | `QueryConditionBuilder` |
| [`createRangeCondition()`](#method-createRangeCondition) static | Returns a condition matching the nodes whose boundaries lie within the given range, inclusive. | `QueryConditionBuilder` |
| [`createShiftCondition()`](#method-createShiftCondition) static | Returns a condition matching the nodes whose boundary value is at least the given value. | `QueryConditionBuilder` |
| [`createSubtreeMoveCondition()`](#method-createSubtreeMoveCondition) static | Returns a condition matching a subtree, including its root, within its current tree. | `QueryConditionBuilder` |

## Method details

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

```php
public static function createChildrenCondition(string $leftAttribute, int $leftValue, string $rightAttribute, int $rightValue, false|string $treeAttribute = false, mixed $treeValue = null, string|null $depthAttribute = null, int|null $parentDepth = null, int|null $maxRelativeDepth = null): array<int|string, mixed>
```

Returns a condition matching the descendants of a node, optionally limited to a maximum depth below it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$leftValue` | `int` | Left value of the ancestor. |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$rightValue` | `int` | Right value of the ancestor. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |
| `$depthAttribute` | `string\|null` | Name of the depth attribute, or `null` to skip depth filtering. |
| `$parentDepth` | `int\|null` | Depth of the ancestor; required together with `$maxRelativeDepth`. |
| `$maxRelativeDepth` | `int\|null` | Maximum number of levels below the ancestor, or `null` for all descendants. |

**Returns**

`array<int|string, mixed>`: Condition matching the descendants.

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

```php
public static function createCrossTreeMoveCondition(string $attribute, int $value, string $treeAttribute, mixed $treeValue): array<int|string, mixed>
```

Returns a condition matching the nodes of a tree whose boundary value is at least the given value.

Opens space in the destination tree before a subtree moves into it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$attribute` | `string` | Name of the left or right boundary attribute to compare. |
| `$value` | `int` | Lowest boundary value to match, inclusive. |
| `$treeAttribute` | `string` | Name of the tree attribute. |
| `$treeValue` | `mixed` | Identifier of the tree that receives the subtree. |

**Returns**

`array<int|string, mixed>`: Condition matching the nodes to shift.

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

```php
public static function createLeavesCondition(string $leftAttribute, string $rightAttribute, false|string $treeAttribute = false, mixed $treeValue = null, int|null $parentLeftValue = null, int|null $parentRightValue = null): array<int|string, mixed>
```

Returns a condition matching the leaf nodes strictly inside the given ancestor boundaries.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |
| `$parentLeftValue` | `int\|null` | Left value of the ancestor whose leaves are matched. |
| `$parentRightValue` | `int\|null` | Right value of the ancestor whose leaves are matched. |

**Returns**

`array<int|string, mixed>`: Condition matching the leaf descendants.

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

```php
public static function createNextSiblingCondition(string $leftAttribute, int $rightValue, false|string $treeAttribute = false, mixed $treeValue = null): array<int|string, mixed>
```

Returns a condition matching the node whose left value immediately follows the given right value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$rightValue` | `int` | Right value of the reference node. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |

**Returns**

`array<int|string, mixed>`: Condition matching the next sibling.

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

```php
public static function createOffsetUpdates(yii\db\Connection $db, array<string, int> $attributeOffsets): array<string, yii\db\Expression>
```

Returns column expressions for `updateAll()` that add a signed offset to each given attribute.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$db` | [`yii\db\Connection`](/docs/api/yii/db/connection/index.md) | Connection used to quote the column names. |
| `$attributeOffsets` | `array<string, int>` | Signed offsets indexed by attribute name. |

**Returns**

`array<string,` [`yii\db\Expression`](/docs/api/yii/db/expression/index.md)`>`: Offset expressions indexed by attribute name.

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

```php
public static function createParentsCondition(string $leftAttribute, int $leftValue, string $rightAttribute, int $rightValue, false|string $treeAttribute = false, mixed $treeValue = null, string|null $depthAttribute = null, int|null $childDepth = null, int|null $maxRelativeDepth = null): array<int|string, mixed>
```

Returns a condition matching the ancestors of a node, optionally limited to a maximum number of levels above it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$leftValue` | `int` | Left value of the node. |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$rightValue` | `int` | Right value of the node. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |
| `$depthAttribute` | `string\|null` | Name of the depth attribute, or `null` to skip depth filtering. |
| `$childDepth` | `int\|null` | Depth of the node; required together with `$maxRelativeDepth`. |
| `$maxRelativeDepth` | `int\|null` | Maximum number of levels above the node, or `null` for all ancestors. |

**Returns**

`array<int|string, mixed>`: Condition matching the ancestors.

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

```php
public static function createPrevSiblingCondition(string $rightAttribute, int $leftValue, false|string $treeAttribute = false, mixed $treeValue = null): array<int|string, mixed>
```

Returns a condition matching the node whose right value immediately precedes the given left value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$leftValue` | `int` | Left value of the reference node. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |

**Returns**

`array<int|string, mixed>`: Condition matching the previous sibling.

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

```php
public static function createRangeCondition(string $leftAttribute, int $leftValue, string $rightAttribute, int $rightValue, false|string $treeAttribute = false, mixed $treeValue = null): array<int|string, mixed>
```

Returns a condition matching the nodes whose boundaries lie within the given range, inclusive.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$leftValue` | `int` | Lowest left value to match. |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$rightValue` | `int` | Highest right value to match. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |

**Returns**

`array<int|string, mixed>`: Condition matching the subtree, including its root.

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

```php
public static function createShiftCondition(string $attribute, int $value, false|string $treeAttribute = false, mixed $treeValue = null): array<int|string, mixed>
```

Returns a condition matching the nodes whose boundary value is at least the given value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$attribute` | `string` | Name of the left or right boundary attribute to compare. |
| `$value` | `int` | Lowest boundary value to match, inclusive. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$treeValue` | `mixed` | Tree identifier to match; ignored when `$treeAttribute` is `false`. |

**Returns**

`array<int|string, mixed>`: Condition matching the nodes to shift.

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

```php
public static function createSubtreeMoveCondition(string $leftAttribute, int $leftValue, string $rightAttribute, int $rightValue, false|string $treeAttribute, mixed $currentTreeValue): array<int|string, mixed>
```

Returns a condition matching a subtree, including its root, within its current tree.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$leftAttribute` | `string` | Name of the left boundary attribute. |
| `$leftValue` | `int` | Left value of the subtree root. |
| `$rightAttribute` | `string` | Name of the right boundary attribute. |
| `$rightValue` | `int` | Right value of the subtree root. |
| `$treeAttribute` | `false\|string` | Name of the tree attribute, or `false` when multiple trees are disabled. |
| `$currentTreeValue` | `mixed` | Identifier of the tree that currently contains the subtree. |

**Returns**

`array<int|string, mixed>`: Condition matching the subtree to move.