QueryConditionBuilder

API reference › Nested sets behavior › QueryConditionBuilder

final class	yii2\extensions\nestedsets\QueryConditionBuilder
Source	src/QueryConditionBuilder.php

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

Methods

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

Method details

createChildrenCondition()

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()

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()

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()

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()

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	Connection used to quote the column names.
$attributeOffsets	array<string, int>	Signed offsets indexed by attribute name.

Returns

array<string, yii\db\Expression>: Offset expressions indexed by attribute name.

createParentsCondition()

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()

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()

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()

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()

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.