October\Rain\Database\Traits\NestedTree

Overview

NestedTree is a 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.


Protected Properties

protected int $moveToNewParentId

moveToNewParentId indicates if the model should be aligned to new parent.


Public Methods

public static bootNestedTree()

public static bootNestedTree(): void

bootNestedTree constructor

public deleteDescendants()

public deleteDescendants(): void

deleteDescendants deletes a branch off the tree, shifting all the elements on the right back to the left so the counts work.

public getAll()

public getAll($columns =  0 => '*']): [October\Rain\Database\Collection 

getAll returns all nodes and children.

public getAllChildren()

public getAllChildren(): October\Rain\Database\Collection 

getAllChildren returns all children down the tree.

public getAllChildrenAndSelf()

public getAllChildrenAndSelf(): October\Rain\Database\Collection 

getAllChildrenAndSelf returns all children and self.

public getChildCount()

public getChildCount(): int 

getChildCount returns number of all children below it.

public getChildren()

public getChildren(): October\Rain\Database\Collection 

getChildren returns direct child nodes.

public getDepth()

public getDepth(): int 

getDepth column value.

public getDepthColumnName()

public getDepthColumnName(): string 

public getEagerChildren()

public getEagerChildren(): October\Rain\Database\Collection 

getEagerChildren returns direct child nodes, with ->children eager loaded.

public getEagerRoot()

public getEagerRoot(): October\Rain\Database\Collection 

getEagerRoot returns a list of all root nodes, with children eager loaded.

public getLeaves()

public getLeaves(): October\Rain\Database\Collection 

getLeaves returns all final nodes without children.

public getLeft()

public getLeft(): int 

getLeft column value.

public getLeftColumnName()

public getLeftColumnName(): string 

public getLeftSibling()

public getLeftSibling(): October\Rain\Database\Model 

public getLevel()

public getLevel(): int 

getLevel returns the level of this node in the tree. Root level is 0.

public getParent()

public getParent(): October\Rain\Database\Collection 

getParent returns the direct parent node.

public getParentColumnName()

public getParentColumnName(): string 

public getParentId()

public getParentId(): int 

getParentId gets value of the model parent_id column.

public getParents()

public getParents(): October\Rain\Database\Collection 

getParents returns all parents up the tree.

public getParentsAndSelf()

public getParentsAndSelf(): October\Rain\Database\Collection 

getParentsAndSelf returns all parents up the tree and self.

public getQualifiedDepthColumnName()

public getQualifiedDepthColumnName(): string 

public getQualifiedLeftColumnName()

public getQualifiedLeftColumnName(): string 

public getQualifiedParentColumnName()

public getQualifiedParentColumnName(): string 

public getQualifiedRightColumnName()

public getQualifiedRightColumnName(): string 

public getRight()

public getRight(): int 

getRight column value.

public getRightColumnName()

public getRightColumnName(): string 

public getRightSibling()

public getRightSibling(): October\Rain\Database\Model 

public getRoot()

public getRoot(): October\Rain\Database\Model 

getRoot returns the root node starting from the current node.

public getRootList()

public getRootList(
    $column,
    $key = null,
    $indent = '   '
): array 

getRootList returns an array column/key pair of all root nodes, with children eager loaded.

public getSiblings()

public getSiblings(): October\Rain\Database\Collection 

getSiblings returns all siblings (parent's children).

public getSiblingsAndSelf()

public getSiblingsAndSelf(): October\Rain\Database\Collection 

public initializeNestedTree()

public initializeNestedTree(): void

initializeNestedTree constructor

public isChild()

public isChild(): bool 

isChild returns true if this is a child node.

public isDescendantOf()

public isDescendantOf(NestedSet $other): bool 

isDescendantOf returns true if node is a descendant.

public isInsideSubtree()

public isInsideSubtree(Model $node): bool 

isInsideSubtree checks if the supplied node is inside the subtree of this model.

public isLeaf()

public isLeaf(): bool 

isLeaf returns true if this is a leaf node (end of a branch).

public isRoot()

public isRoot(): bool 

isRoot returns true if this is a root node.

public makeChildOf()

public makeChildOf($node): October\Rain\Database\Model 

makeChildOf makes model node a child of specified node.

public makeRoot()

public makeRoot(): October\Rain\Database\Model 

makeRoot makes this model a root node.

public moveAfter()

public moveAfter($node): October\Rain\Database\Model 

moveAfter moves to the model to after (right) a specified node.

public moveBefore()

public moveBefore($node): October\Rain\Database\Model 

moveBefore moves to the model to before (left) specified node.

public moveLeft()

public moveLeft(): October\Rain\Database\Model 

moveLeft finds the left sibling and move to left of it.

public moveRight()

public moveRight(): October\Rain\Database\Model 

moveRight finds the right sibling and move to the right of it.

public moveToNewParent()

public moveToNewParent(): void

moveToNewParent will realign the nesting if the parent identifier is dirty.

public newCollection()

public newCollection($models = []): void

newCollection returns a custom TreeCollection collection.

public resetTreeNesting()

public resetTreeNesting(): void

resetTreeNesting can be used to repair corrupt or missing tree definitions, it will flatten and heal the necessary columns, all parent and child associations are retained.

public resetTreeOrphans()

public resetTreeOrphans(): void

resetTreeOrphans can be used to locate orphaned records, those that refer to a parent_id value where the associated record no longer exists, and promote them to be visible in the collection again, by setting the parent column to null.

public restoreDescendants()

public restoreDescendants(): void

restoreDescendants of the current node.

public scopeAllChildren()

public scopeAllChildren(
    $query,
    $includeSelf = false
): Illuminate\Database\Query\Builder 

scopeAllChildren sets of all children & nested children.

public scopeGetAllRoot()

public scopeGetAllRoot($query): October\Rain\Database\Collection 

scopeGetAllRoot returns a list of all root nodes, without eager loading.

public scopeGetNested()

public scopeGetNested($query): Collection 

scopeGetNested is a non-chaining scope, returns an eager loaded hierarchy tree. Children are eager loaded inside the $model->children relation.

public scopeLeaves()

public scopeLeaves($query): Illuminate\Database\Query\Builder 

scopeLeaves returns all final nodes without children.

public scopeListsNested()

public scopeListsNested(
    string $column,
    string $key,
    string $indent = null,
    $indent = '   '
): array 

scopeListsNested gets an array with values of a given column. Values are indented according to their depth.

public scopeParents()

public scopeParents(
    $query,
    $includeSelf = false
): Illuminate\Database\Eloquent\Builder 

scopeParents returns a prepared query with all parents up the tree.

public scopeSiblings()

public scopeSiblings(
    $query,
    $includeSelf = false
): Illuminate\Database\Eloquent\Builder 

scopeSiblings filters targeting all children of the parent, except self.

public scopeWithoutNode()

public scopeWithoutNode($query, $node): Illuminate\Database\Query\Builder 

scopeWithoutNode extracts a certain node object from the current query expression.

public scopeWithoutRoot()

public scopeWithoutRoot($query): Illuminate\Database\Query\Builder 

scopeWithoutRoot extracts first root (from the current node context) from current query expression.

public scopeWithoutSelf()

public scopeWithoutSelf($query): Illuminate\Database\Query\Builder 

scopeWithoutSelf extracts current node (self) from current query expression.

public setDefaultLeftAndRight()

public setDefaultLeftAndRight(): void 

setDefaultLeftAndRight columns

public setDepth()

public setDepth(): October\Rain\Database\Model 

setDepth sets the depth attribute.

public shiftSiblingsForRestore()

public shiftSiblingsForRestore(): void

shiftSiblingsForRestore allocates a slot for the the current node between its siblings.

public storeNewParent()

public storeNewParent(): void

storeNewParent handles if the parent column is modified so it can be realigned.

Protected Methods

protected getOtherBoundary()

protected getOtherBoundary($node, $target, $position): int 

getOtherBoundary calculates the other boundary.

protected getPrimaryBoundary()

protected getPrimaryBoundary($node, $target, $position): int 

getPrimaryBoundary calculates the boundary.

protected getSortedBoundaries()

protected getSortedBoundaries($node, $target, $position): array 

getSortedBoundaries calculates a sorted boundaries array.

protected moveTo()

protected moveTo(
    mixed $target,
    string $position
): October\Rain\Database\Model 

moveTo is a handler for all node alignments.

protected newNestedTreeQuery()

protected newNestedTreeQuery(): void

newNestedTreeQuery creates a new query for nested sets

protected performMove()

protected performMove($node, $target, $position): int 

performMove executes the SQL query associated with the update of the indexes affected by the move operation.

protected resolveMoveTarget()

protected resolveMoveTarget($targetId): October\Rain\Database\Model|null 

protected validateMove()

protected validateMove($node, $target, $position): void 

validateMove validates a proposed move and returns true if changes are needed.