This is a Laravel 4-5 package for working with trees in relational databases.
- Laravel 5.2, 5.3 is supported since v4
- Laravel 5.1 is supported in v3
- Laravel 4 is supported in v2
Although this project is completely free for use, I appreciate any support!
- Donate via PayPal
- My Visa: 4276 0700 1073 4244
Contents:
Nested sets or Nested Set Model is a way to effectively store hierarchical data in a relational table. From wikipedia:
The nested set model is to number the nodes according to a tree traversal, which visits each node twice, assigning numbers in the order of visiting, and at both visits. This leaves two numbers for each node, which are stored as two attributes. Querying becomes inexpensive: hierarchy membership can be tested by comparing these numbers. Updating requires renumbering and is therefore expensive.
NSM shows good performance when tree is updated rarely. It is tuned to be fast for getting related nodes. It'is ideally suited for building multi-depth menu or categories for shop.
Suppose that we have a model Category
; a $node
variable is an instance of that model
and the node that we are manipulating. It can be a fresh model or one from database.
Node has following relationships that are fully functional and can be eagerly loaded:
- Node belongs to
parent
- Node has many
children
- Node has many
descendants
Moving and inserting nodes includes several database queries, so transaction is automatically started when node is saved. It is safe to use global transaction if you work with several models.
Another important note is that structural manipulations are deferred until you
hit save
on model (some methods implicitly call save
and return boolean result
of the operation).
If model is successfully saved it doesn't mean that node was moved. If your application
depends on whether the node has actually changed its position, use hasMoved
method:
if ($node->save()) {
$moved = $node->hasMoved();
}
When you simply creating a node, it will be appended to the end of the tree:
Category::create($attributes); // Saved as root
$node = new Category($attributes);
$node->save(); // Saved as root
In this case the node is considered a root which means that it doesn't have a parent.
// #1 Implicit save
$node->saveAsRoot();
// #2 Explicit save
$node->makeRoot()->save();
The node will be appended to the end of the tree.
If you want to make node a child of other node, you can make it last or first child.
In following examples, $parent
is some existing node.
There are few ways to append a node:
// #1 Using deferred insert
$node->appendToNode($parent)->save();
// #2 Using parent node
$parent->appendNode($node);
// #3 Using parent's children relationship
$parent->children()->create($attributes);
// #5 Using node's parent relationship
$node->parent()->associate($parent)->save();
// #6 Using the parent attribute
$node->parent_id = $parent->id;
$node->save();
// #7 Using static method
Category::create($attributes, $parent);
And only a couple ways to prepend:
// #1
$node->prependToNode($parent)->save();
// #2
$parent->prependNode($node);
You can make $node
to be a neighbor of the $neighbor
node using following methods:
$neighbor
must exists, target node can be fresh. If target node exists,
it will be moved to the new position and parent will be changed if it's required.
# Explicit save
$node->afterNode($neighbor)->save();
$node->beforeNode($neighbor)->save();
# Implicit save
$node->insertAfterNode($neighbor);
$node->insertBeforeNode($neighbor);
When using static method create
on node, it checks whether attributes contains
children
key. If it does, it creates more nodes recursively.
$node = Category::create([
'name' => 'Foo',
'children' => [
[
'name' => 'Bar',
'children' => [
[ 'name' => 'Baz' ],
],
],
],
]);
$node->children
now contains a list of created child nodes.
You can easily rebuild a tree. This is useful for mass-changing the structure of the tree.
Category::rebuildTree($data, $delete);
$data
is an array of nodes:
$data = [
[ 'id' => 1, 'name' => 'foo', 'children' => [ ... ] ],
[ 'name' => 'bar' ],
];
There is an id specified for node with the name of foo
which means that existing
node will be filled and saved. If node is not exists ModelNotFoundException
is
thrown. Also, this node has children
specified which is also an array of nodes;
they will be processed in the same manner and saved as children of node foo
.
Node bar
has no primary key specified, so it will be created.
$delete
shows whether to delete nodes that are already exists but not present
in $data
. By default, nodes aren't deleted.
In some cases we will use an $id
variable which is an id of the target node.
Ancestors make a chain of parents to the node. Helpful for displaying breadcrumbs to the current category.
// #1 Using accessor
$result = $node->getAncestors();
// #2 Using a query
$result = $node->ancestors()->get();
// #3 Getting ancestors by primary key
$result = Category::ancestorsOf($id);
Descendants are all nodes in a sub tree, i.e. children of node, children of children, etc.
// #1 Using relationship
$result = $node->descendants;
// #2 Using a query
$result = $node->descendants()->get();
// #3 Getting descendants by primary key
$result = Category::descendantsOf($id);
Descendants can be eagerly loaded:
$nodes = Category::with('descendants')->whereIn('id', $idList)->get();
Siblings are nodes that have same parent.
$result = $node->getSiblings();
$result = $node->siblings()->get();
To get only next siblings:
// Get a sibling that is immediately after the node
$result = $node->getNextSibling();
// Get all siblings that are after the node
$result = $node->getNextSiblings();
// Get all siblings using a query
$result = $node->nextSiblings()->get();
To get previous siblings:
// Get a sibling that is immediately before the node
$result = $node->getPrevSibling();
// Get all siblings that are before the node
$result = $node->getPrevSiblings();
// Get all siblings using a query
$result = $node->prevSiblings()->get();
Imagine that each category has many
goods. I.e. HasMany
relationship is established.
How can you get all goods of $category
and every its descendant? Easy!
// Get ids of descendants
$categories = $category->descendants()->lists('id');
// Include the id of category itself
$categories[] = $category->getKey();
// Get goods
$goods = Goods::whereIn('category_id', $categories)->get();
If you need to know at which level the node is:
$result = Category::withDepth()->find($id);
$depth = $result->depth;
Root node will be at level 0. Children of root nodes will have a level of 1, etc.
To get nodes of specified level, you can apply having
constraint:
$result = Category::withDepth()->having('depth', '=', 1)->get();
Each node has it's own unique _lft
value that determines its position in the tree. If
you want node to be ordered by this value, you can use defaultOrder
method on
the query builder:
// All nodes will now be ordered by lft value
$result = Category::defaultOrder()->get();
You can get nodes in reversed order:
$result = Category::reversed()->get();
To shift node up or down inside parent to affect default order:
$bool = $node->down();
$bool = $node->up();
// Shift node by 3 siblings
$bool = $node->down(3);
The result of the operation is boolean value of whether the node has changed its position.
Various constraints that can be applied to the query builder:
- whereIsRoot() to get only root nodes;
- whereIsAfter($id) to get every node (not just siblings) that are after a node with specified id;
- whereIsBefore($id) to get every node that is before a node with specified id.
Descendants constraints:
$result = Category::whereDescendantOf($node)->get();
$result = Category::whereNotDescendantOf($node)->get();
$result = Category::orWhereDescendantOf($node)->get();
$result = Category::orWhereNotDescendantOf($node)->get();
Ancestor constraints:
$result = Category::whereAncestorOf($node)->get();
$node
can be either a primary key of the model or model instance.
After getting a set of nodes, you can convert it to tree. For example:
$tree = Category::get()->toTree();
This will fill parent
and children
relationships on every node in the set and
you can render a tree using recursive algorithm:
$nodes = Category::get()->toTree();
$traverse = function ($categories, $prefix = '-') use (&$traverse) {
foreach ($categories as $category) {
echo PHP_EOL.$prefix.' '.$category->name;
$traverse($category->children, $prefix.'-');
}
};
$traverse($nodes);
This will output something like this:
- Root
-- Child 1
--- Sub child 1
-- Child 2
- Another root
Also, you can build a flat tree: a list of nodes where child nodes are immediately after parent node. This is helpful when you get nodes with custom order (i.e. alphabetically) and don't want to use recursion to iterate over your nodes.
$nodes = Category::get()->toFlatTree();
Sometimes you don't need whole tree to be loaded and just some subtree of specific node. It is show in following example:
$root = Category::find($rootId);
$tree = $root->descendants->toTree($root);
Now $tree
contains children of $root
node.
If you don't need $root
node itself, do following instead:
$tree = Category::descendantsOf($rootId)->toTree($rootId);
To delete a node:
$node->delete();
IMPORTANT! Any descendant that node has will also be deleted!
IMPORTANT! Nodes are required to be deleted as models, don't try do delete them using a query like so:
Category::where('id', '=', $id)->delete();
This will break the tree!
SoftDeletes
trait is supported, also on model level.
To check if node is a descendant of other node:
$bool = $node->isDescendantOf($parent);
To check whether the node is a root:
$bool = $node->isRoot();
Other checks:
$node->isChildOf($other);
$node->isAncestorOf($other);
$node->isSiblingOf($other);
You can check whether a tree is broken (i.e. has some structural errors):
$bool = Category::isBroken();
It is possible to get error statistics:
$data = Category::countErrors();
It will return an array with following keys:
oddness
-- the number of nodes that have wrong set oflft
andrgt
valuesduplicates
-- the number of nodes that have samelft
orrgt
valueswrong_parent
-- the number of nodes that have invalidparent_id
value that doesn't correspond tolft
andrgt
valuesmissing_parent
-- the number of nodes that haveparent_id
pointing to node that doesn't exists
Since v3.1 tree can now be fixed. Using inheritance info from parent_id
column,
proper _lft
and _rgt
values are set for every node.
Node::fixTree();
Imagine you have Menu
model and MenuItems
. There is a one-to-many relationship
set up between these models. MenuItem
has menu_id
attribute for joining models
together. MenuItem
incorporates nested sets. It is obvious that you would want to
process each tree separately based on menu_id
attribute. In order to do so, you
need to specify this attribute as scope attribute:
protected function getScopeAttributes()
{
return [ 'menu_id' ];
}
But now in order to execute some custom query, you need to provide attributes that are used for scoping:
MenuItem::scoped([ 'menu_id' => 5 ])->withDepth()->get(); // OK
MenuItem::descendantsOf($id)->get(); // WRONG: returns nodes from other scope
MenuItem::scoped([ 'menu_id' => 5 ])->fixTree();
When requesting nodes using model instance, scopes applied automatically based on the attributes of that model. See examples:
$node = MenuItem::findOrFail($id);
$node->siblings()->withDepth()->get(); // OK
To get scoped query builder using instance:
$node->newScopedQuery();
Note, that scoping is not required when retrieving model by primary key (since the key is unique):
$node = MenuItem::findOrFail($id); // OK
$node = MenuItem::scoped([ 'menu_id' => 5 ])->findOrFail(); // OK, but redundant
- PHP >= 5.4
- Laravel >= 4.1
It is highly suggested to use database that supports transactions (like MySql's InnoDb) to secure a tree from possible corruption.
To install the package, in terminal:
composer require kalnoy/nestedset
You can use a method to add needed columns with default names:
Schema::create('table', function (Blueprint $table) {
...
NestedSet::columns($table);
});
To drop columns:
Schema::table('table', function (Blueprint $table) {
NestedSet::dropColumns($table);
});
Your model should use Kalnoy\Nestedset\NodeTrait
trait to enable nested sets:
use Kalnoy\Nestedset\NodeTrait;
class Foo extends Model {
use NodeTrait;
}
If your previous extension used different set of columns, you just need to override following methods on your model class:
public function getLftName()
{
return 'left';
}
public function getRgtName()
{
return 'right';
}
public function getParentIdName()
{
return 'parent';
}
// Specify parent id attribute mutator
public function setParentAttribute($value)
{
$this->setParentIdAttribute($value);
}
If your tree contains parent_id
info, you need to add two columns to your schema:
$table->unsignedInteger('_lft');
$table->unsignedInteger('_rgt');
After setting up your model you only need to fix the tree to fill
_lft
and _rgt
columns:
MyModel::fixTree();
Copyright (c) 2016 Alexander Kalnoy
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.