PHP Class Baum\Node

This abstract class implements Nested Set functionality. A Nested Set is a smart way to implement an ordered tree with the added benefit that you can select all of their descendants with a single query. Drawbacks are that insertion or move operations need more complex sql queries. Nested sets are appropiate when you want either an ordered tree (menus, commercial categories, etc.) or an efficient way of querying big trees.
Inheritance: extends Baum\Extensions\Eloquent\Model
Show file Open project: gazsp/baum Class Usage Examples

Protected Properties

Property Type Description
$depthColumn string Column name for depth field.
$guarded array Guard NestedSet fields from mass-assignment.
$leftColumn string Column name for left index.
$moveToNewParentId integer Indicates whether we should move to a new parent.
$orderColumn string Column to perform the default sorting.
$parentColumn string Column name to store the reference to parent's node.
$rightColumn string Column name for right index.
$scoped array Columns which restrict what we consider our Nested Set list.

Public Methods

Method Description
all ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection | static[] Get all of the nodes from the database.
allLeaves ( ) : Builder Static query scope. Returns a query scope with all nodes which are at the end of a branch.
allTrunks ( ) : Builder Static query scope. Returns a query scope with all nodes which are at the middle of a branch (not root and not leaves).
ancestors ( ) : Builder Instance scope which targets all the ancestor chain nodes excluding the current one.
ancestorsAndSelf ( ) : Builder Instance scope which targes all the ancestor chain nodes including the current one.
buildTree ( $nodeList ) : boolean Maps the provided tree structure into the database.
children ( ) : Illuminate\Database\Eloquent\Relations\HasMany Children relation (self-referential) 1-N.
descendants ( ) : Builder Set of all children & nested children.
descendantsAndSelf ( ) : Builder Scope targeting itself and all of its nested children.
destroyDescendants ( ) : void; Prunes a branch off the tree, shifting all the elements on the right back to the left so the counts work.
equals ( $node ) : boolean Equals?
getAncestors ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Get all the ancestor chain from the database excluding the current node.
getAncestorsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Get all the ancestor chain from the database including the current node.
getAncestorsAndSelfWithoutRoot ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Get all the ancestor chain from the database including the current node but without the root node.
getAncestorsWithoutRoot ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Get all the ancestor chain from the database excluding the current node and the root node (from the current node's perspective).
getDepth ( ) : integer Get the model's "depth" value.
getDepthColumnName ( ) : string Get the "depth" field column name.
getDescendants ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Retrieve all of its children & nested children.
getDescendantsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Retrieve all nested children an self.
getImmediateDescendants ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Retrive all of its "immediate" descendants.
getLeaves ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Return all of its nested children which do not have children.
getLeft ( ) : integer Get the value of the model's "left" field.
getLeftColumnName ( ) : string Get the "left" field column name.
getLeftSibling ( ) : NestedSet Returns the first sibling to the left.
getLevel ( ) : integer Returns the level of this node in the tree.
getNestedList ( $column, $key = null, $seperator = ' ' ) : array Return an key-value array indicating the node's depth with $seperator.
getOrder ( ) : mixed Get the model's "order" value.
getOrderColumnName ( ) : string Get the "order" field column name.
getOthersAtSameDepth ( ) : Illuminate\Database\Eloquent\Collection Retrieve all other nodes at the same depth,.
getParentColumnName ( ) : string Get the parent column name.
getParentId ( ) : integer Get the value of the models "parent_id" field.
getQualifiedDepthColumnName ( ) : string Get the table qualified "depth" field column name.
getQualifiedLeftColumnName ( ) : string Get the table qualified "left" field column name.
getQualifiedOrderColumnName ( ) : string Get the table qualified "order" field column name.
getQualifiedParentColumnName ( ) : string Get the table qualified parent column name.
getQualifiedRightColumnName ( ) : string Get the table qualified "right" field column name.
getQualifiedScopedColumns ( ) : array Get the qualified column names which define our scope.
getRight ( ) : integer Get the value of the model's "right" field.
getRightColumnName ( ) : string Get the "right" field column name.
getRightSibling ( ) : NestedSet Returns the first sibling to the right.
getRoot ( ) : NestedSet Returns the root node starting at the current node.
getScopedColumns ( ) : array Get the column names which define our scope.
getSiblings ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Return all children of the parent, except self.
getSiblingsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Get all children of the parent, including self.
getTrunks ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection Return all of its nested children which are trunks.
immediateDescendants ( ) : Builder Set of "immediate" descendants (aka children), alias for the children relation.
inSameScope ( $other ) : boolean Checkes if the given node is in the same scope as the current one.
insideSubtree ( $node ) : boolean Checks wether the given node is a descendant of itself. Basically, whether its in the subtree defined by the left and right indices.
isAncestorOf ( $other ) : boolean Returns true if node is an ancestor.
isChild ( ) : boolean Returns true if this is a child node.
isDescendantOf ( $other ) : boolean Returns true if node is a descendant.
isLeaf ( ) : boolean Returns true if this is a leaf node (end of a branch).
isRoot ( ) : boolean Returns true if this is a root node.
isScoped ( ) : boolean Returns wether this particular node instance is scoped by certain fields or not.
isSelfOrAncestorOf ( $other ) : boolean Returns true if node is self or an ancestor.
isSelfOrDescendantOf ( $other ) : boolean Returns true if node is self or a descendant.
isTrunk ( ) : boolean Returns true if this is a trunk node (not root or leaf).
isValidNestedSet ( ) : boolean Checks wether the underlying Nested Set structure is valid.
leaves ( ) : Builder Instance scope targeting all of its nested children which do not have children.
makeChildOf ( $node ) : Node Make the node a child of .
makeFirstChildOf ( $node ) : Node Make the node the first child of .
makeLastChildOf ( $node ) : Node Make the node the last child of .
makeNextSiblingOf ( $node ) : Node Alias for moveToRightOf.
makePreviousSiblingOf ( $node ) : Node Alias for moveToLeftOf.
makeRoot ( ) : Node Make current node a root node.
makeSiblingOf ( $node ) : Node Alias for moveToRightOf.
makeTree ( $nodeList ) : boolean Maps the provided tree structure into the database using the current node as the parent. The provided tree structure will be inserted/updated as the descendancy subtree of the current node instance.
moveLeft ( ) : Node Find the left sibling and move to left of it.
moveRight ( ) : Node Find the right sibling and move to the right of it.
moveToLeftOf ( $node ) : Node Move to the node to the left of .
moveToNewParent ( ) : void Move to the new parent if appropiate.
moveToRightOf ( $node ) : Node Move to the node to the right of .
newCollection ( array $models = [] ) : Collection Overload new Collection.
newNestedSetQuery ( ) : Builder | static Get a new "scoped" query builder for the Node's model.
parent ( ) : BelongsTo Parent relation (self-referential) 1-1.
rebuild ( ) : void Rebuilds the structure of the current Nested Set.
restoreDescendants ( ) : void Restores all of the current node's descendants.
root ( ) : NestedSet Returns the first root node.
roots ( ) : Builder Static query scope. Returns a query scope with all root nodes.
scopeLimitDepth ( $query, $limit ) : Builder Provides a depth level limit for the query.
scopeWithoutNode ( $query, $node ) : Builder Query scope which extracts a certain node object from the current query expression.
scopeWithoutRoot ( $query ) : Builder Extracts first root (from the current node p-o-v) from current query expression.
scopeWithoutSelf ( $query ) : Builder Extracts current node (self) from current query expression.
setDefaultLeftAndRight ( ) : void Sets default values for left and right fields.
setDepth ( ) : Node Sets the depth attribute.
setDepthWithSubtree ( ) : Node Sets the depth attribute for the current node and all of its descendants.
shiftSiblingsForRestore ( ) : void "Makes room" for the the current node between its siblings.
siblings ( ) : Builder Instance scope targeting all children of the parent, except self.
siblingsAndSelf ( ) : Builder Instance scope which targets all children of the parent, including self.
storeNewParent ( ) : void Store the parent_id if the attribute is modified so as we are able to move the node to this new parent after saving.
trunks ( ) : Builder Instance scope targeting all of its nested children which are between the root and the leaf nodes (middle branch).

Protected Methods

Method Description
boot ( ) : void The "booting" method of the model.
computeLevel ( ) : integer Compute current node level. If could not move past ourseleves return our ancestor count, otherwhise get the first parent level + the computed nesting.
determineDepth ( Baum\Node $node, integer $nesting ) : array Return an array with the last node we could reach and its nesting level.
moveTo ( Baum\Node | integer $target, string $position ) : Node Main move method. Here we handle all node movements with the corresponding lft/rgt index updates.

Method Details

all() public static method

Get all of the nodes from the database.
public static all ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection | static[]
$columns array
return Illuminate\Database\Eloquent\Collection | static[]

allLeaves() public static method

Static query scope. Returns a query scope with all nodes which are at the end of a branch.
public static allLeaves ( ) : Builder
return Illuminate\Database\Query\Builder

allTrunks() public static method

Static query scope. Returns a query scope with all nodes which are at the middle of a branch (not root and not leaves).
public static allTrunks ( ) : Builder
return Illuminate\Database\Query\Builder

ancestors() public method

Instance scope which targets all the ancestor chain nodes excluding the current one.
public ancestors ( ) : Builder
return Illuminate\Database\Eloquent\Builder

ancestorsAndSelf() public method

Instance scope which targes all the ancestor chain nodes including the current one.
public ancestorsAndSelf ( ) : Builder
return Illuminate\Database\Eloquent\Builder

boot() protected static method

We'll use this method to register event listeners on a Node instance as suggested in the beta documentation... TODO: - Find a way to avoid needing to declare the called methods "public" as registering the event listeners *inside* this methods does not give us an object context. Events: 1. "creating": Before creating a new Node we'll assign a default value for the left and right indexes. 2. "saving": Before saving, we'll perform a check to see if we have to move to another parent. 3. "saved": Move to the new parent after saving if needed and re-set depth. 4. "deleting": Before delete we should prune all children and update the left and right indexes for the remaining nodes. 5. (optional) "restoring": Before a soft-delete node restore operation, shift its siblings. 6. (optional) "restore": After having restored a soft-deleted node, restore all of its descendants.
protected static boot ( ) : void
return void

buildTree() public static method

Maps the provided tree structure into the database.
public static buildTree ( $nodeList ) : boolean
return boolean

children() public method

Children relation (self-referential) 1-N.
public children ( ) : Illuminate\Database\Eloquent\Relations\HasMany
return Illuminate\Database\Eloquent\Relations\HasMany

computeLevel() protected method

Compute current node level. If could not move past ourseleves return our ancestor count, otherwhise get the first parent level + the computed nesting.
protected computeLevel ( ) : integer
return integer

descendants() public method

Set of all children & nested children.
public descendants ( ) : Builder
return Illuminate\Database\Query\Builder

descendantsAndSelf() public method

Scope targeting itself and all of its nested children.
public descendantsAndSelf ( ) : Builder
return Illuminate\Database\Query\Builder

destroyDescendants() public method

Prunes a branch off the tree, shifting all the elements on the right back to the left so the counts work.
public destroyDescendants ( ) : void;
return void;

determineDepth() protected method

Return an array with the last node we could reach and its nesting level.
protected determineDepth ( Baum\Node $node, integer $nesting ) : array
$node Baum\Node
$nesting integer
return array

equals() public method

Equals?
public equals ( $node ) : boolean
return boolean

getAncestors() public method

Get all the ancestor chain from the database excluding the current node.
public getAncestors ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getAncestorsAndSelf() public method

Get all the ancestor chain from the database including the current node.
public getAncestorsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getAncestorsAndSelfWithoutRoot() public method

Get all the ancestor chain from the database including the current node but without the root node.
public getAncestorsAndSelfWithoutRoot ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getAncestorsWithoutRoot() public method

Get all the ancestor chain from the database excluding the current node and the root node (from the current node's perspective).
public getAncestorsWithoutRoot ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getDepth() public method

Get the model's "depth" value.
public getDepth ( ) : integer
return integer

getDepthColumnName() public method

Get the "depth" field column name.
public getDepthColumnName ( ) : string
return string

getDescendants() public method

Retrieve all of its children & nested children.
public getDescendants ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getDescendantsAndSelf() public method

Retrieve all nested children an self.
public getDescendantsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getImmediateDescendants() public method

Retrive all of its "immediate" descendants.
public getImmediateDescendants ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getLeaves() public method

Return all of its nested children which do not have children.
public getLeaves ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getLeft() public method

Get the value of the model's "left" field.
public getLeft ( ) : integer
return integer

getLeftColumnName() public method

Get the "left" field column name.
public getLeftColumnName ( ) : string
return string

getLeftSibling() public method

Returns the first sibling to the left.
public getLeftSibling ( ) : NestedSet
return NestedSet

getLevel() public method

Root level is 0.
public getLevel ( ) : integer
return integer

getNestedList() public static method

Return an key-value array indicating the node's depth with $seperator.
public static getNestedList ( $column, $key = null, $seperator = ' ' ) : array
return array

getOrder() public method

Get the model's "order" value.
public getOrder ( ) : mixed
return mixed

getOrderColumnName() public method

Get the "order" field column name.
public getOrderColumnName ( ) : string
return string

getOthersAtSameDepth() public method

Retrieve all other nodes at the same depth,.
public getOthersAtSameDepth ( ) : Illuminate\Database\Eloquent\Collection
return Illuminate\Database\Eloquent\Collection

getParentColumnName() public method

Get the parent column name.
public getParentColumnName ( ) : string
return string

getParentId() public method

Get the value of the models "parent_id" field.
public getParentId ( ) : integer
return integer

getQualifiedDepthColumnName() public method

Get the table qualified "depth" field column name.
public getQualifiedDepthColumnName ( ) : string
return string

getQualifiedLeftColumnName() public method

Get the table qualified "left" field column name.
public getQualifiedLeftColumnName ( ) : string
return string

getQualifiedOrderColumnName() public method

Get the table qualified "order" field column name.
public getQualifiedOrderColumnName ( ) : string
return string

getQualifiedParentColumnName() public method

Get the table qualified parent column name.
public getQualifiedParentColumnName ( ) : string
return string

getQualifiedRightColumnName() public method

Get the table qualified "right" field column name.
public getQualifiedRightColumnName ( ) : string
return string

getQualifiedScopedColumns() public method

Get the qualified column names which define our scope.
public getQualifiedScopedColumns ( ) : array
return array

getRight() public method

Get the value of the model's "right" field.
public getRight ( ) : integer
return integer

getRightColumnName() public method

Get the "right" field column name.
public getRightColumnName ( ) : string
return string

getRightSibling() public method

Returns the first sibling to the right.
public getRightSibling ( ) : NestedSet
return NestedSet

getRoot() public method

Returns the root node starting at the current node.
public getRoot ( ) : NestedSet
return NestedSet

getScopedColumns() public method

Get the column names which define our scope.
public getScopedColumns ( ) : array
return array

getSiblings() public method

Return all children of the parent, except self.
public getSiblings ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getSiblingsAndSelf() public method

Get all children of the parent, including self.
public getSiblingsAndSelf ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

getTrunks() public method

Return all of its nested children which are trunks.
public getTrunks ( array $columns = ['*'] ) : Illuminate\Database\Eloquent\Collection
$columns array
return Illuminate\Database\Eloquent\Collection

immediateDescendants() public method

Set of "immediate" descendants (aka children), alias for the children relation.
public immediateDescendants ( ) : Builder
return Illuminate\Database\Query\Builder

inSameScope() public method

Checkes if the given node is in the same scope as the current one.
public inSameScope ( $other ) : boolean
return boolean

insideSubtree() public method

Checks wether the given node is a descendant of itself. Basically, whether its in the subtree defined by the left and right indices.
public insideSubtree ( $node ) : boolean
return boolean

isAncestorOf() public method

Returns true if node is an ancestor.
public isAncestorOf ( $other ) : boolean
return boolean

isChild() public method

Returns true if this is a child node.
public isChild ( ) : boolean
return boolean

isDescendantOf() public method

Returns true if node is a descendant.
public isDescendantOf ( $other ) : boolean
return boolean

isLeaf() public method

Returns true if this is a leaf node (end of a branch).
public isLeaf ( ) : boolean
return boolean

isRoot() public method

Returns true if this is a root node.
public isRoot ( ) : boolean
return boolean

isScoped() public method

Returns wether this particular node instance is scoped by certain fields or not.
public isScoped ( ) : boolean
return boolean

isSelfOrAncestorOf() public method

Returns true if node is self or an ancestor.
public isSelfOrAncestorOf ( $other ) : boolean
return boolean

isSelfOrDescendantOf() public method

Returns true if node is self or a descendant.
public isSelfOrDescendantOf ( $other ) : boolean
return boolean

isTrunk() public method

Returns true if this is a trunk node (not root or leaf).
public isTrunk ( ) : boolean
return boolean

isValidNestedSet() public static method

Checks wether the underlying Nested Set structure is valid.
public static isValidNestedSet ( ) : boolean
return boolean

leaves() public method

Instance scope targeting all of its nested children which do not have children.
public leaves ( ) : Builder
return Illuminate\Database\Query\Builder

makeChildOf() public method

..
public makeChildOf ( $node ) : Node
return Node

makeFirstChildOf() public method

..
public makeFirstChildOf ( $node ) : Node
return Node

makeLastChildOf() public method

..
public makeLastChildOf ( $node ) : Node
return Node

makeNextSiblingOf() public method

Alias for moveToRightOf.
public makeNextSiblingOf ( $node ) : Node
return Node

makePreviousSiblingOf() public method

Alias for moveToLeftOf.
public makePreviousSiblingOf ( $node ) : Node
return Node

makeRoot() public method

Make current node a root node.
public makeRoot ( ) : Node
return Node

makeSiblingOf() public method

Alias for moveToRightOf.
public makeSiblingOf ( $node ) : Node
return Node

makeTree() public method

Maps the provided tree structure into the database using the current node as the parent. The provided tree structure will be inserted/updated as the descendancy subtree of the current node instance.
public makeTree ( $nodeList ) : boolean
return boolean

moveLeft() public method

Find the left sibling and move to left of it.
public moveLeft ( ) : Node
return Node

moveRight() public method

Find the right sibling and move to the right of it.
public moveRight ( ) : Node
return Node

moveTo() protected method

Main move method. Here we handle all node movements with the corresponding lft/rgt index updates.
protected moveTo ( Baum\Node | integer $target, string $position ) : Node
$target Baum\Node | integer
$position string
return Node

moveToLeftOf() public method

..
public moveToLeftOf ( $node ) : Node
return Node

moveToNewParent() public method

Move to the new parent if appropiate.
public moveToNewParent ( ) : void
return void

moveToRightOf() public method

..
public moveToRightOf ( $node ) : Node
return Node

newCollection() public method

Overload new Collection.
public newCollection ( array $models = [] ) : Collection
$models array
return Baum\Extensions\Eloquent\Collection

newNestedSetQuery() public method

Get a new "scoped" query builder for the Node's model.
public newNestedSetQuery ( ) : Builder | static
return Illuminate\Database\Eloquent\Builder | static

parent() public method

Parent relation (self-referential) 1-1.
public parent ( ) : BelongsTo
return Illuminate\Database\Eloquent\Relations\BelongsTo

rebuild() public static method

Rebuilds the structure of the current Nested Set.
public static rebuild ( ) : void
return void

restoreDescendants() public method

Restores all of the current node's descendants.
public restoreDescendants ( ) : void
return void

root() public static method

Returns the first root node.
public static root ( ) : NestedSet
return NestedSet

roots() public static method

Static query scope. Returns a query scope with all root nodes.
public static roots ( ) : Builder
return Illuminate\Database\Query\Builder

scopeLimitDepth() public method

Provides a depth level limit for the query.
public scopeLimitDepth ( $query, $limit ) : Builder
return Illuminate\Database\Query\Builder

scopeWithoutNode() public method

Query scope which extracts a certain node object from the current query expression.
public scopeWithoutNode ( $query, $node ) : Builder
return Illuminate\Database\Query\Builder

scopeWithoutRoot() public method

Extracts first root (from the current node p-o-v) from current query expression.
public scopeWithoutRoot ( $query ) : Builder
return Illuminate\Database\Query\Builder

scopeWithoutSelf() public method

Extracts current node (self) from current query expression.
public scopeWithoutSelf ( $query ) : Builder
return Illuminate\Database\Query\Builder

setDefaultLeftAndRight() public method

Sets default values for left and right fields.
public setDefaultLeftAndRight ( ) : void
return void

setDepth() public method

Sets the depth attribute.
public setDepth ( ) : Node
return Node

setDepthWithSubtree() public method

Sets the depth attribute for the current node and all of its descendants.
public setDepthWithSubtree ( ) : Node
return Node

shiftSiblingsForRestore() public method

"Makes room" for the the current node between its siblings.
public shiftSiblingsForRestore ( ) : void
return void

siblings() public method

Instance scope targeting all children of the parent, except self.
public siblings ( ) : Builder
return Illuminate\Database\Eloquent\Builder

siblingsAndSelf() public method

Instance scope which targets all children of the parent, including self.
public siblingsAndSelf ( ) : Builder
return Illuminate\Database\Eloquent\Builder

storeNewParent() public method

Store the parent_id if the attribute is modified so as we are able to move the node to this new parent after saving.
public storeNewParent ( ) : void
return void

trunks() public method

Instance scope targeting all of its nested children which are between the root and the leaf nodes (middle branch).
public trunks ( ) : Builder
return Illuminate\Database\Query\Builder

Property Details

$depthColumn protected property

Column name for depth field.
protected string $depthColumn
return string

$guarded protected property

Guard NestedSet fields from mass-assignment.
protected array $guarded
return array

$leftColumn protected property

Column name for left index.
protected string $leftColumn
return string

$moveToNewParentId protected static property

Indicates whether we should move to a new parent.
protected static int $moveToNewParentId
return integer

$orderColumn protected property

Column to perform the default sorting.
protected string $orderColumn
return string

$parentColumn protected property

Column name to store the reference to parent's node.
protected string $parentColumn
return string

$rightColumn protected property

Column name for right index.
protected string $rightColumn
return string

$scoped protected property

Columns which restrict what we consider our Nested Set list.
protected array $scoped
return array