NestedTree
Nested set model trait
Model table must have parent_id, nest_left, nest_right and nest_depth table columns. In the model class definition:
use \October\Rain\Database\Traits\NestedTree;
$table->integer('parent_id')->nullable(); $table->integer('nest_left')->nullable(); $table->integer('nest_right')->nullable(); $table->integer('nest_depth')->nullable();
You can change the column names used by declaring:
const PARENT_ID = 'my_parent_column'; const NEST_LEFT = 'my_left_column'; const NEST_RIGHT = 'my_right_column'; const NEST_DEPTH = 'my_depth_column';
General access methods:
$model->getRoot(); // Returns the highest parent of a node. $model->getRootList(); // Returns an indented array of key and value columns from root. $model->getParent(); // The direct parent node. $model->getParents(); // Returns all parents up the tree. $model->getParentsAndSelf(); // Returns all parents up the tree and self. $model->getChildren(); // Set of all direct child nodes. $model->getSiblings(); // Return all siblings (parent's children). $model->getSiblingsAndSelf(); // Return all siblings and self. $model->getLeaves(); // Returns all final nodes without children. $model->getDepth(); // Returns the depth of a current node. $model->getChildCount(); // Returns number of all children.
Query builder methods:
$query->withoutNode(); // Filters a specific node from the results. $query->withoutSelf(); // Filters current node from the results. $query->withoutRoot(); // Filters root from the results. $query->children(); // Filters as direct children down the tree. $query->allChildren(); // Filters as all children down the tree. $query->parent(); // Filters as direct parent up the tree. $query->parents(); // Filters as all parents up the tree. $query->siblings(); // Filters as all siblings (parent's children). $query->leaves(); // Filters as all final nodes without children. $query->getNested(); // Returns an eager loaded collection of results. $query->listsNested(); // Returns an indented array of key and value columns.
Flat result access methods:
$model->getAll(); // Returns everything in correct order. $model->getAllRoot(); // Returns all root nodes. $model->getAllChildren(); // Returns all children down the tree. $model->getAllChildrenAndSelf(); // Returns all children and self.
Eager loaded access methods:
$model->getEagerRoot(); // Returns a list of all root nodes, with ->children eager loaded. $model->getEagerChildren(); // Returns direct child nodes, with ->children eager loaded.
Table of Contents
- $moveToNewParentId : int
- bootNestedTree() : mixed
- deleteDescendants() : void
- Deletes a branch off the tree, shifting all the elements on the right back to the left so the counts work.
- getAll() : Collection
- Returns all nodes and children.
- getAllChildren() : Collection
- Returns all children down the tree.
- getAllChildrenAndSelf() : Collection
- Returns all children and self.
- getChildCount() : int
- Returns number of all children below it.
- getChildren() : Collection
- Returns direct child nodes.
- getDepth() : int
- Get value of the depth column.
- getDepthColumnName() : string
- Get depth column name.
- getEagerChildren() : Collection
- Returns direct child nodes, with ->children eager loaded.
- getEagerRoot() : Collection
- Returns a list of all root nodes, with children eager loaded.
- getLeaves() : Collection
- Returns all final nodes without children.
- getLeft() : int
- Get value of the left column.
- getLeftColumnName() : string
- Get left column name.
- getLeftSibling() : Model
- Return left sibling
- getLevel() : int
- Returns the level of this node in the tree.
- getParent() : Collection
- The direct parent node.
- getParentColumnName() : string
- Get parent column name.
- getParentId() : int
- Get value of the model parent_id column.
- getParents() : Collection
- Returns all parents up the tree.
- getParentsAndSelf() : Collection
- Returns all parents up the tree and self.
- getQualifiedDepthColumnName() : string
- Get fully qualified depth column name.
- getQualifiedLeftColumnName() : string
- Get fully qualified left column name.
- getQualifiedParentColumnName() : string
- Get fully qualified parent column name.
- getQualifiedRightColumnName() : string
- Get fully qualified right column name.
- getRight() : int
- Get value of the right column.
- getRightColumnName() : string
- Get right column name.
- getRightSibling() : Model
- Return right sibling
- getRoot() : Model
- Returns the root node starting from the current node.
- getRootList() : array<string|int, mixed>
- Returns an array column/key pair of all root nodes, with children eager loaded.
- getSiblings() : Collection
- Return all siblings (parent's children).
- getSiblingsAndSelf() : Collection
- Return all siblings and self.
- isChild() : bool
- Returns true if this is a child node.
- isDescendantOf() : bool
- Returns true if node is a descendant.
- isInsideSubtree() : bool
- Checks if the supplied node is inside the subtree of this model.
- isLeaf() : bool
- Returns true if this is a leaf node (end of a branch).
- isRoot() : bool
- Returns true if this is a root node.
- makeChildOf() : Model
- Make model node a child of specified node.
- makeRoot() : Model
- Make this model a root node.
- moveAfter() : Model
- Move to the model to after (right) a specified node.
- moveBefore() : Model
- Move to the model to before (left) specified node.
- moveLeft() : Model
- Find the left sibling and move to left of it.
- moveRight() : Model
- Find the right sibling and move to the right of it.
- moveToNewParent() : void
- If the parent identifier is dirty, realign the nesting.
- newCollection() : mixed
- Return a custom TreeCollection collection
- restoreDescendants() : void
- Restores all of the current node descendants.
- scopeAllChildren() : Builder
- Set of all children & nested children.
- scopeGetAllRoot() : Collection
- Returns a list of all root nodes, without eager loading
- scopeGetNested() : Collection
- Non chaining scope, returns an eager loaded hierarchy tree. Children are eager loaded inside the $model->children relation.
- scopeLeaves() : Builder
- Returns all final nodes without children.
- scopeListsNested() : array<string|int, mixed>
- Gets an array with values of a given column. Values are indented according to their depth.
- scopeParents() : Builder
- Returns a prepared query with all parents up the tree.
- scopeSiblings() : Builder
- Filter targeting all children of the parent, except self.
- scopeWithoutNode() : Builder
- Query scope which extracts a certain node object from the current query expression.
- scopeWithoutRoot() : Builder
- Extracts first root (from the current node context) from current query expression.
- scopeWithoutSelf() : Builder
- Extracts current node (self) from current query expression.
- setDefaultLeftAndRight() : void
- Set defaults for left and right columns.
- setDepth() : Model
- Sets the depth attribute
- shiftSiblingsForRestore() : void
- Allocates a slot for the the current node between its siblings.
- storeNewParent() : void
- Handle if the parent column is modified so it can be realigned.
- getOtherBoundary() : int
- Calculates the other boundary.
- getPrimaryBoundary() : int
- Calculates the boundary.
- getSortedBoundaries() : array<string|int, mixed>
- Calculates a sorted boundaries array.
- moveTo() : Model
- Handler for all node alignments.
- performMove() : int
- Executes the SQL query associated with the update of the indexes affected by the move operation.
- validateMove() : void
- Validates a proposed move and returns true if changes are needed.
Properties
$moveToNewParentId
protected
int
$moveToNewParentId
= null
Indicates if the model should be aligned to new parent.
Methods
bootNestedTree()
public
static bootNestedTree() : mixed
Return values
mixed —deleteDescendants()
Deletes a branch off the tree, shifting all the elements on the right back to the left so the counts work.
public
deleteDescendants() : void
Return values
void —getAll()
Returns all nodes and children.
public
getAll([mixed $columns = ['*'] ]) : Collection
Parameters
- $columns : mixed = ['*']
Return values
Collection —getAllChildren()
Returns all children down the tree.
public
getAllChildren() : Collection
Return values
Collection —getAllChildrenAndSelf()
Returns all children and self.
public
getAllChildrenAndSelf() : Collection
Return values
Collection —getChildCount()
Returns number of all children below it.
public
getChildCount() : int
Return values
int —getChildren()
Returns direct child nodes.
public
getChildren() : Collection
Return values
Collection —getDepth()
Get value of the depth column.
public
getDepth() : int
Return values
int —getDepthColumnName()
Get depth column name.
public
getDepthColumnName() : string
Return values
string —getEagerChildren()
Returns direct child nodes, with ->children eager loaded.
public
getEagerChildren() : Collection
Return values
Collection —getEagerRoot()
Returns a list of all root nodes, with children eager loaded.
public
getEagerRoot() : Collection
Return values
Collection —getLeaves()
Returns all final nodes without children.
public
getLeaves() : Collection
Return values
Collection —getLeft()
Get value of the left column.
public
getLeft() : int
Return values
int —getLeftColumnName()
Get left column name.
public
getLeftColumnName() : string
Return values
string —getLeftSibling()
Return left sibling
public
getLeftSibling() : Model
Return values
Model —getLevel()
Returns the level of this node in the tree.
public
getLevel() : int
Root level is 0.
Return values
int —getParent()
The direct parent node.
public
getParent() : Collection
Return values
Collection —getParentColumnName()
Get parent column name.
public
getParentColumnName() : string
Return values
string —getParentId()
Get value of the model parent_id column.
public
getParentId() : int
Return values
int —getParents()
Returns all parents up the tree.
public
getParents() : Collection
Return values
Collection —getParentsAndSelf()
Returns all parents up the tree and self.
public
getParentsAndSelf() : Collection
Return values
Collection —getQualifiedDepthColumnName()
Get fully qualified depth column name.
public
getQualifiedDepthColumnName() : string
Return values
string —getQualifiedLeftColumnName()
Get fully qualified left column name.
public
getQualifiedLeftColumnName() : string
Return values
string —getQualifiedParentColumnName()
Get fully qualified parent column name.
public
getQualifiedParentColumnName() : string
Return values
string —getQualifiedRightColumnName()
Get fully qualified right column name.
public
getQualifiedRightColumnName() : string
Return values
string —getRight()
Get value of the right column.
public
getRight() : int
Return values
int —getRightColumnName()
Get right column name.
public
getRightColumnName() : string
Return values
string —getRightSibling()
Return right sibling
public
getRightSibling() : Model
Return values
Model —getRoot()
Returns the root node starting from the current node.
public
getRoot() : Model
Return values
Model —getRootList()
Returns an array column/key pair of all root nodes, with children eager loaded.
public
getRootList(mixed $column[, mixed $key = null ][, mixed $indent = ' ' ]) : array<string|int, mixed>
Parameters
- $column : mixed
- $key : mixed = null
- $indent : mixed = ' '
Return values
array<string|int, mixed> —getSiblings()
Return all siblings (parent's children).
public
getSiblings() : Collection
Return values
Collection —getSiblingsAndSelf()
Return all siblings and self.
public
getSiblingsAndSelf() : Collection
Return values
Collection —isChild()
Returns true if this is a child node.
public
isChild() : bool
Return values
bool —isDescendantOf()
Returns true if node is a descendant.
public
isDescendantOf(mixed $other) : bool
Parameters
- $other : mixed
Return values
bool —isInsideSubtree()
Checks if the supplied node is inside the subtree of this model.
public
isInsideSubtree(mixed $node) : bool
Parameters
- $node : mixed
Return values
bool —isLeaf()
Returns true if this is a leaf node (end of a branch).
public
isLeaf() : bool
Return values
bool —isRoot()
Returns true if this is a root node.
public
isRoot() : bool
Return values
bool —makeChildOf()
Make model node a child of specified node.
public
makeChildOf(mixed $node) : Model
Parameters
- $node : mixed
Return values
Model —makeRoot()
Make this model a root node.
public
makeRoot() : Model
Return values
Model —moveAfter()
Move to the model to after (right) a specified node.
public
moveAfter(mixed $node) : Model
Parameters
- $node : mixed
Return values
Model —moveBefore()
Move to the model to before (left) specified node.
public
moveBefore(mixed $node) : Model
Parameters
- $node : mixed
Return values
Model —moveLeft()
Find the left sibling and move to left of it.
public
moveLeft() : Model
Return values
Model —moveRight()
Find the right sibling and move to the right of it.
public
moveRight() : Model
Return values
Model —moveToNewParent()
If the parent identifier is dirty, realign the nesting.
public
moveToNewParent() : void
Return values
void —newCollection()
Return a custom TreeCollection collection
public
newCollection([array<string|int, mixed> $models = [] ]) : mixed
Parameters
- $models : array<string|int, mixed> = []
Return values
mixed —restoreDescendants()
Restores all of the current node descendants.
public
restoreDescendants() : void
Return values
void —scopeAllChildren()
Set of all children & nested children.
public
scopeAllChildren(mixed $query[, mixed $includeSelf = false ]) : Builder
Parameters
- $query : mixed
- $includeSelf : mixed = false
Return values
Builder —scopeGetAllRoot()
Returns a list of all root nodes, without eager loading
public
scopeGetAllRoot(mixed $query) : Collection
Parameters
- $query : mixed
Return values
Collection —scopeGetNested()
Non chaining scope, returns an eager loaded hierarchy tree. Children are eager loaded inside the $model->children relation.
public
scopeGetNested(mixed $query) : Collection
Parameters
- $query : mixed
Return values
Collection —A collection
scopeLeaves()
Returns all final nodes without children.
public
scopeLeaves(mixed $query) : Builder
Parameters
- $query : mixed
Return values
Builder —scopeListsNested()
Gets an array with values of a given column. Values are indented according to their depth.
public
scopeListsNested(mixed $query, string $column[, string $key = null ][, string $indent = ' ' ]) : array<string|int, mixed>
Parameters
- $query : mixed
- $column : string
-
Array values
- $key : string = null
-
Array keys
- $indent : string = ' '
-
Character to indent depth
Return values
array<string|int, mixed> —scopeParents()
Returns a prepared query with all parents up the tree.
public
scopeParents(mixed $query[, mixed $includeSelf = false ]) : Builder
Parameters
- $query : mixed
- $includeSelf : mixed = false
Return values
Builder —scopeSiblings()
Filter targeting all children of the parent, except self.
public
scopeSiblings(mixed $query[, mixed $includeSelf = false ]) : Builder
Parameters
- $query : mixed
- $includeSelf : mixed = false
Return values
Builder —scopeWithoutNode()
Query scope which extracts a certain node object from the current query expression.
public
scopeWithoutNode(mixed $query, mixed $node) : Builder
Parameters
- $query : mixed
- $node : mixed
Return values
Builder —scopeWithoutRoot()
Extracts first root (from the current node context) from current query expression.
public
scopeWithoutRoot(mixed $query) : Builder
Parameters
- $query : mixed
Return values
Builder —scopeWithoutSelf()
Extracts current node (self) from current query expression.
public
scopeWithoutSelf(mixed $query) : Builder
Parameters
- $query : mixed
Return values
Builder —setDefaultLeftAndRight()
Set defaults for left and right columns.
public
setDefaultLeftAndRight() : void
Return values
void —setDepth()
Sets the depth attribute
public
setDepth() : Model
Return values
Model —shiftSiblingsForRestore()
Allocates a slot for the the current node between its siblings.
public
shiftSiblingsForRestore() : void
Return values
void —storeNewParent()
Handle if the parent column is modified so it can be realigned.
public
storeNewParent() : void
Return values
void —getOtherBoundary()
Calculates the other boundary.
protected
getOtherBoundary(mixed $node, mixed $target, mixed $position) : int
Parameters
- $node : mixed
- $target : mixed
- $position : mixed
Return values
int —getPrimaryBoundary()
Calculates the boundary.
protected
getPrimaryBoundary(mixed $node, mixed $target, mixed $position) : int
Parameters
- $node : mixed
- $target : mixed
- $position : mixed
Return values
int —getSortedBoundaries()
Calculates a sorted boundaries array.
protected
getSortedBoundaries(mixed $node, mixed $target, mixed $position) : array<string|int, mixed>
Parameters
- $node : mixed
- $target : mixed
- $position : mixed
Return values
array<string|int, mixed> —moveTo()
Handler for all node alignments.
protected
moveTo(mixed $target, string $position) : Model
Parameters
- $target : mixed
- $position : string
Return values
Model —performMove()
Executes the SQL query associated with the update of the indexes affected by the move operation.
protected
performMove(mixed $node, mixed $target, mixed $position) : int
Parameters
- $node : mixed
- $target : mixed
- $position : mixed
Return values
int —validateMove()
Validates a proposed move and returns true if changes are needed.
protected
validateMove(mixed $node, mixed $target, mixed $position) : void
Parameters
- $node : mixed
- $target : mixed
- $position : mixed