1. Documentation
  2. API
  3. Library
  4. Database
  5. Traits
  6. NestedTree

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.