yajra / baum
Baum 是 Eloquent 模型嵌套集模式的实现。
Requires
- php: >=5.4.0
- illuminate/console: 5.*
- illuminate/database: 5.*
- illuminate/events: 5.*
- illuminate/filesystem: 5.*
- illuminate/support: 5.*
Requires (Dev)
- d11wtq/boris: ~1.0.10
- mockery/mockery: ~0.9
- phpunit/phpunit: ~4.0
README
Baum 是为 Laravel 5 的 Eloquent ORM 实现的嵌套集模式。
Laravel 4.2.x 兼容性,请检查 1.0.x 分支 或使用最新的 1.0.x 标签版本。
注意
此项目是 Baum 的一个分支,维护以使用 Laravel-OCI8 包与 Oracle 一起工作。
文档
关于嵌套集
嵌套集是一种智能的方式来实现一个有 序 的树,允许快速、非递归查询。例如,您可以在单个查询中获取一个节点的所有后代,无论树的深度如何。缺点是插入/移动/删除需要复杂的 SQL,但这个包在幕后处理这些操作!
嵌套集适用于有顺序的树(例如,菜单、商业分类)和必须高效查询的大树(例如,线程帖子)。
有关更多信息,请参阅嵌套集的维基百科条目。此外,这是一个很好的入门教程:http://www.evanpetersen.com/item/nested-sets.html
理论背后的内容,快速阅读版
要直观地了解嵌套集的工作方式,可以想象一个父实体包围其所有子实体,然后是父实体的父实体,等等。因此,这个树
root
|_ Child 1
|_ Child 1.1
|_ Child 1.2
|_ Child 2
|_ Child 2.1
|_ Child 2.2
可以表示为这样
___________________________________________________________________
| Root |
| ____________________________ ____________________________ |
| | Child 1 | | Child 2 | |
| | __________ _________ | | __________ _________ | |
| | | C 1.1 | | C 1.2 | | | | C 2.1 | | C 2.2 | | |
1 2 3_________4 5________6 7 8 9_________10 11_______12 13 14
| |___________________________| |___________________________| |
|___________________________________________________________________|
这些数字代表左边界和右边界。然后表可能看起来像这样
id | parent_id | lft | rgt | depth | data
1 | | 1 | 14 | 0 | root
2 | 1 | 2 | 7 | 1 | Child 1
3 | 2 | 3 | 4 | 2 | Child 1.1
4 | 2 | 5 | 6 | 2 | Child 1.2
5 | 1 | 8 | 13 | 1 | Child 2
6 | 5 | 9 | 10 | 2 | Child 2.1
7 | 5 | 11 | 12 | 2 | Child 2.2
要获取 父 节点的所有子节点,您可以
SELECT * WHERE lft IS BETWEEN parent.lft AND parent.rgt
要获取子节点数,它是
(right - left - 1)/2
要获取一个节点及其所有祖先(返回到根节点),您可以
SELECT * WHERE node.lft IS BETWEEN lft AND rgt
如您所见,在普通树中通常是递归且速度极慢的查询,现在突然变得非常快。是不是很酷?
安装
Baum 与 Laravel 5 及以上版本兼容。您可以通过将以下内容添加到 composer.json
文件中来将其添加到您的项目中
"baum/baum": "~1.1"
运行 composer install
来安装它。
与大多数 Laravel 5 包一样,接下来您需要注册 Baum 服务提供者。为此,请转到您的 config/app.php
文件,并将以下行添加到 providers
数组中
'Baum\Providers\BaumServiceProvider',
入门
在包正确安装后,开始使用提供生成器是最简单的方法。
php artisan baum:install MODEL
将模型替换为您计划用于嵌套集模型的类名。
生成器将安装迁移文件和模型文件到您的应用程序中,这些文件配置为与 Baum 提供的嵌套集行为一起工作。您应该查看这些文件,因为每个文件都描述了如何对其进行自定义。
接下来,您可能会运行 artisan migrate
来应用迁移。
模型配置
为了与 Baum 一起工作,您必须确保您的模型类扩展 Baum\Node
。
这已经是最简单的方式了
class Category extends Baum\Node { }
这是一个 稍微 复杂的示例,其中列名已自定义
class Dictionary extends Baum\Node { protected $table = 'dictionary'; // 'parent_id' column name protected $parentColumn = 'parent_id'; // 'lft' column name protected $leftColumn = 'lidx'; // 'rgt' column name protected $rightColumn = 'ridx'; // 'depth' column name protected $depthColumn = 'nesting'; // guard attributes from mass-assignment protected $guarded = array('id', 'parent_id', 'lidx', 'ridx', 'nesting'); }
请记住,显然,列名必须与数据库表中的列名匹配。
迁移配置
您必须确保支持Baum模型的数据库表具有以下列
parent_id
:父引用(整型)lft
:左索引边界(整型)rgt
:右索引边界(整型)depth
:深度或嵌套级别(整型)
以下是一个示例迁移文件
class Category extends Migration { public function up() { Schema::create('categories', function(Blueprint $table) { $table->increments('id'); $table->integer('parent_id')->nullable(); $table->integer('lft')->nullable(); $table->integer('rgt')->nullable(); $table->integer('depth')->nullable(); $table->string('name', 255); $table->timestamps(); }); } public function down() { Schema::drop('categories'); } }
您可以自由修改列名,但必须在迁移和模型中同时更改它们。
用法
在配置完模型并运行迁移后,您现在可以使用Baum了。下面是一些示例。
- 创建根节点
- 插入节点
- 删除节点
- 获取节点的嵌套级别
- 移动节点
- 向节点提问
- 关系
- 根和叶作用域
- 访问祖先/后代链
- 限制返回的子级级别
- 自定义排序列
- 导出层次树
- 模型事件:
moving
和moved
- 作用域支持
- 验证
- 树重建
- 软删除
- 种子/批量赋值
- 杂项/实用函数
创建根节点
默认情况下,所有节点都创建为根节点
$root = Category::create(['name' => 'Root category']);
或者,您可能需要将现有节点转换为根节点
$node->makeRoot();
您还可以将其parent_id
列设置为null以实现相同的行为
// This works the same as makeRoot() $node->parent_id = null; $node->save();
插入节点
// Directly with a relation $child1 = $root->children()->create(['name' => 'Child 1']); // with the `makeChildOf` method $child2 = Category::create(['name' => 'Child 2']); $child2->makeChildOf($root);
删除节点
$child1->delete();
被删除节点的后代也将被删除,并且所有lft
和rgt
边界将被重新计算。请注意,目前不会触发后代deleting
和deleted
模型事件。
获取节点的嵌套级别
getLevel()
方法将返回节点的当前嵌套级别或深度。
$node->getLevel() // 0 when root
移动节点
Baum提供了一些方法来移动节点
moveLeft()
:找到左兄弟并移动到它的左边。moveRight()
:找到右兄弟并移动到它的右边。moveToLeftOf($otherNode)
:移动到...的左边节点moveToRightOf($otherNode)
:移动到...的右边节点makeNextSiblingOf($otherNode)
:moveToRightOf
的别名。makeSiblingOf($otherNode)
:makeNextSiblingOf
的别名。makePreviousSiblingOf($otherNode)
:moveToLeftOf
的别名。makeChildOf($otherNode)
:使节点成为...的子节点。makeFirstChildOf($otherNode)
:使节点成为...的第一个子节点。makeLastChildOf($otherNode)
:makeChildOf
的别名。makeRoot()
:使当前节点成为根节点。
例如
$root = Creatures::create(['name' => 'The Root of All Evil']); $dragons = Creatures::create(['name' => 'Here Be Dragons']); $dragons->makeChildOf($root); $monsters = new Creatures(['name' => 'Horrible Monsters']); $monsters->save(); $monsters->makeSiblingOf($dragons); $demons = Creatures::where('name', '=', 'demons')->first(); $demons->moveToLeftOf($dragons);
向节点提问
您可以向Baum节点提出一些问题
isRoot()
:如果这是根节点则返回true。isLeaf()
:如果这是叶子节点(分支的末尾)则返回true。isChild()
:如果这是子节点则返回true。isDescendantOf($other)
:如果节点是其他节点的后代则返回true。isSelfOrDescendantOf($other)
:如果节点是自身或后代则返回true。isAncestorOf($other)
:如果节点是其他节点的祖先则返回true。isSelfOrAncestorOf($other)
:如果节点是自身或祖先则返回true。equals($node)
:当前节点实例等于其他节点。insideSubtree($node)
:检查给定的节点是否在由左和右索引定义的子树内。inSameScope($node)
:如果给定的节点与当前节点在相同的作用域内则返回true。即,如果每个在scoped
属性中的列在两个节点中都有相同的值。
使用上一个示例中的节点
$demons->isRoot(); // => false $demons->isDescendantOf($root) // => true
关系
Baum为您提供了两个自引用Eloquent关系:parent
和children
。
$parent = $node->parent()->get(); $children = $node->children()->get();
根和叶作用域
Baum提供了一些基本的查询作用域,用于访问根和叶节点
// Query scope which targets all root nodes Category::roots() // All leaf nodes (nodes at the end of a branch) Category:allLeaves()
您可能还只对第一个根感兴趣
$firstRootNode = Category::root();
访问祖先/后代链
Baum提供了几种方法来访问嵌套集树中节点的祖先/后代链。需要记住的主要一点是,它们以两种方式提供:
首先作为查询作用域,返回一个Illuminate\Database\Eloquent\Builder
实例以继续查询。要从这些中获取实际的结果,请记住调用get()
或first()
。
ancestorsAndSelf()
:针对包括当前节点在内的所有祖先链节点。ancestors()
:查询不包括当前节点的祖先链节点。siblingsAndSelf()
:实例作用域,针对包括自身在内的父节点的所有子节点。siblings()
:实例作用域,针对除自身以外的父节点的所有子节点。leaves()
:实例作用域,针对没有子节点的所有嵌套子节点。descendantsAndSelf()
:针对自身及其所有嵌套子节点的作用域。descendants()
:所有子节点和嵌套子节点集合。immediateDescendants()
:所有子节点集合(非递归)。
其次,作为返回实际Baum\Node
实例的方法(在适当的情况下,包含在Collection
对象中)
getRoot()
:从当前节点返回根节点。getAncestorsAndSelf()
:检索包括当前节点在内的所有祖先链。getAncestorsAndSelfWithoutRoot()
:除了根节点外的所有祖先(包括当前节点)。getAncestors()
:从数据库获取不包括当前节点的所有祖先链。getAncestorsWithoutRoot()
:除了当前节点和根节点外的所有祖先。getSiblingsAndSelf()
:获取包括自身在内的父节点的所有子节点。getSiblings()
:返回除自身以外的父节点的所有子节点。getLeaves()
:返回所有没有子节点的嵌套子节点。getDescendantsAndSelf()
:检索所有嵌套子节点和自身。getDescendants()
:检索所有子节点和嵌套子节点。getImmediateDescendants()
:检索所有子节点(非递归)。
以下是一个简单示例,用于迭代节点的后代(假设有一个名称属性可用)
$node = Category::where('name', '=', 'Books')->first(); foreach($node->getDescendantsAndSelf() as $descendant) { echo "{$descendant->name}"; }
限制返回的子级级别
在某些情况下,当层次深度很大时,可能需要限制返回子级的级别(深度)。您可以通过使用Baum中的limitDepth
查询作用域来实现这一点。
以下片段将获取当前节点的后代,最多5个深度级别以下
$node->descendants()->limitDepth(5)->get();
同样,您可以通过提供所需的深度限制作为第一个参数,使用getDescendants
和getDescendantsAndSelf
方法来限制后代级别。
// This will work without depth limiting // 1. As usual $node->getDescendants(); // 2. Selecting only some attributes $other->getDescendants(array('id', 'parent_id', 'name')); ... // With depth limiting // 1. A maximum of 5 levels of children will be returned $node->getDescendants(5); // 2. A max. of 5 levels of children will be returned selecting only some attrs $other->getDescendants(5, array('id', 'parent_id', 'name'));
自定义排序列
在Baum中,默认情况下,所有结果都按lft
索引列值排序,以确保一致性。
如果您希望更改此默认行为,您需要在模型中指定要用于排序结果的列名,如下所示
protected $orderColumn = 'name';
导出层次树
Baum扩展了默认的Eloquent\Collection
类,并为它提供了toHierarchy
方法,该方法返回表示查询树的嵌套集合。
将完整的树层次结构检索到常规的Collection
对象中,并正确嵌套其子节点,就像这样
$tree = Category::where('name', '=', 'Books')->first()->getDescendantsAndSelf()->toHierarchy();
模型事件:moving
和 moved
Baum模型在每次移动节点到嵌套集树时都会触发以下事件:moving
和moved
。这允许您在节点移动过程中挂钩到这些点。与正常的Eloquent模型事件一样,如果从moving
事件中返回false
,则移动操作将被取消。
挂钩到这些事件的推荐方法是使用模型的boot方法
class Category extends Baum\Node { public static function boot() { parent::boot(); static::moving(function($node) { // Before moving the node this function will be called. }); static::moved(function($node) { // After the move operation is processed this function will be // called. }); } }
作用域支持
Baum提供了一种简单的方法来提供嵌套集合的“作用域”限制,这限制了我们将哪些内容视为嵌套集合树的一部分。这应该允许在同一数据库表中存在多个嵌套集合树。
要使用作用域功能,您可以在子类中覆盖scoped
模型属性。该属性应包含一个列名(数据库字段)数组,这些字段将用于限制嵌套集合查询
class Category extends Baum\Node { ... protected $scoped = array('company_id'); ... }
在上面的例子中,company_id
有效地限制了(或“作用域”)一个嵌套集合树。因此,对于该字段的每个值,我们可能能够构造一个完全不同的树。
$root1 = Category::create(['name' => 'R1', 'company_id' => 1]); $root2 = Category::create(['name' => 'R2', 'company_id' => 2]); $child1 = Category::create(['name' => 'C1', 'company_id' => 1]); $child2 = Category::create(['name' => 'C2', 'company_id' => 2]); $child1->makeChildOf($root1); $child2->makeChildOf($root2); $root1->children()->get(); // <- returns $child1 $root2->children()->get(); // <- returns $child2
所有询问或遍历嵌套集合树的方法都将使用scoped
属性(如果提供)。
请注意,目前不支持在作用域之间移动节点。
验证
静态方法::isValidNestedSet()
允许您检查您的底层树结构是否正确。它主要检查以下3件事
- 检查边界索引
lft
、rgt
是否不为空,rgt
值大于lft
且在父节点(如果设置)的范围内。 lft
和rgt
列值没有重复。- 由于第一个检查实际上没有检查根节点,请检查每个根节点的
lft
和rgt
索引是否在其子节点的范围内。
所有检查都是作用域意识的,并且如果需要,将单独检查每个作用域。
示例用法,给定一个Category
节点类
Category::isValidNestedSet() => true
树重建
Baum通过静态方法::rebuild()
支持完整的树结构重建(或重新索引)。
此方法将重新索引所有lft
、rgt
和depth
列值,仅从父节点 <-> 子节点关系的角度检查您的树。这意味着您只需要一个正确填充的parent_id
列,Baum将尽力重新计算其余部分。
当索引值出现严重问题时,这可能会非常有用,或者当需要转换到另一个实现(这可能会有一个parent_id
列)时,它可能非常有用。
此操作也是作用域意识的,如果定义了作用域,将分别重建所有作用域。
简单示例用法,给定一个Category
节点类
Category::rebuild()
有效的树(根据isValidNestedSet
方法)将不会重建。要强制索引重建过程,只需将重建方法的第一参数设置为true
。
Category::rebuild(true);
软删除
Baum对软删除操作提供有限支持。我所说的有限是指测试仍然有限,并且在框架的即将推出的4.2版本中,软删除功能正在发生变化,所以请明智地使用此功能。
目前,您可以认为一个安全的操作restore()
是以下之一:
- 恢复一个叶节点
- 恢复一个父节点未软删除的整个子树
播种/批量赋值
由于嵌套集合结构通常涉及许多方法调用以构建层次结构(这会导致多个数据库查询),Baum提供了两个方便的方法,可以将提供的节点属性数组映射到数据库中
buildTree($nodeList)
:(静态方法)将提供的节点属性数组映射到数据库中。makeTree($nodeList)
:(实例方法)使用当前节点实例作为提供的子树的父节点,将提供的节点属性数组映射到数据库中。
这两种方法将在主键未提供时创建新节点,在主键提供时更新或创建,并删除所有不在作用域中的节点。理解作用域对于buildTree
静态方法是整个嵌套集合树,对于makeTree
实例方法是当前节点的所有后代。
例如,想象一下,我们想要将以下分类层次结构映射到我们的数据库中
- 电视 & 家影院
- 平板电脑 & 电子阅读器
- 电脑
- 笔记本电脑
- PC 笔记本
- Macbook(Air/Pro)
- 台式机
- 显示器
- 笔记本电脑
- 手机
以下代码可以轻松实现这一目标
$categories = [ ['id' => 1, 'name' => 'TV & Home Theather'], ['id' => 2, 'name' => 'Tablets & E-Readers'], ['id' => 3, 'name' => 'Computers', 'children' => [ ['id' => 4, 'name' => 'Laptops', 'children' => [ ['id' => 5, 'name' => 'PC Laptops'], ['id' => 6, 'name' => 'Macbooks (Air/Pro)'] ]], ['id' => 7, 'name' => 'Desktops'], ['id' => 8, 'name' => 'Monitors'] ]], ['id' => 9, 'name' => 'Cell Phones'] ]; Category::buildTree($categories) // => true
之后,我们可以根据需要更新层次结构
$categories = [ ['id' => 1, 'name' => 'TV & Home Theather'], ['id' => 2, 'name' => 'Tablets & E-Readers'], ['id' => 3, 'name' => 'Computers', 'children' => [ ['id' => 4, 'name' => 'Laptops', 'children' => [ ['id' => 5, 'name' => 'PC Laptops'], ['id' => 6, 'name' => 'Macbooks (Air/Pro)'] ]], ['id' => 7, 'name' => 'Desktops', 'children' => [ // These will be created ['name' => 'Towers Only'], ['name' => 'Desktop Packages'], ['name' => 'All-in-One Computers'], ['name' => 'Gaming Desktops'] ]] // This one, as it's not present, will be deleted // ['id' => 8, 'name' => 'Monitors'], ]], ['id' => 9, 'name' => 'Cell Phones'] ]; Category::buildTree($categories); // => true
makeTree
实例方法与此类似。唯一的区别是它将只对调用节点实例的 子节点 执行操作。
现在假设我们已经在数据库中有了以下层次结构
- 电子产品
- 健康与美容
- 小型家电
- 大型家电
如果我们执行以下代码
$children = [ ['name' => 'TV & Home Theather'], ['name' => 'Tablets & E-Readers'], ['name' => 'Computers', 'children' => [ ['name' => 'Laptops', 'children' => [ ['name' => 'PC Laptops'], ['name' => 'Macbooks (Air/Pro)'] ]], ['name' => 'Desktops'], ['name' => 'Monitors'] ]], ['name' => 'Cell Phones'] ]; $electronics = Category::where('name', '=', 'Electronics')->first(); $electronics->makeTree($children); // => true
将得到以下结果
- 电子产品
- 电视 & 家影院
- 平板电脑 & 电子阅读器
- 电脑
- 笔记本电脑
- PC 笔记本
- Macbook(Air/Pro)
- 台式机
- 显示器
- 笔记本电脑
- 手机
- 健康与美容
- 小型家电
- 大型家电
更新和删除子树中的节点方式相同。
杂项/实用函数
节点提取查询范围
Baum 提供了一些查询范围,可以用来从当前结果集中提取(移除)选定的节点。
withoutNode(node)
:从当前结果集中提取指定的节点。withoutSelf()
:从当前结果集中提取自身。withoutRoot()
:从结果集中提取当前根节点。
$node = Category::where('name', '=', 'Some category I do not want to see.')->first(); $root = Category::where('name', '=', 'Old boooks')->first(); var_dump($root->descendantsAndSelf()->withoutNode($node)->get()); ... // <- This result set will not contain $node
获取嵌套列表的列值
getNestedList()
静态方法返回一个键值对数组,表示节点的深度。对于填充 select
元素等很有用。
它期望返回的列名,可选:用作数组键的列(如果没有提供,则使用 id
)和/或分隔符
public static function getNestedList($column, $key = null, $seperator = ' ');
一个示例用例
$nestedList = Category::getNestedList('name'); // $nestedList will contain an array like the following: // array( // 1 => 'Root 1', // 2 => ' Child 1', // 3 => ' Child 2', // 4 => ' Child 2.1', // 5 => ' Child 3', // 6 => 'Root 2' // );
更多信息
您可以在wiki中找到有关 Baum 的更多信息、使用示例和/或常见问题。
完成本 README 后,请随意浏览 wiki
https://github.com/etrepat/baum/wiki
贡献
想要贡献?也许你发现了一些讨厌的 bug?这是个好消息!
- 分支并克隆项目:
git clone git@github.com:your-username/baum.git
。 - 运行测试,并确保它们在您的设置中通过:
phpunit
。 - 创建您的 bugfix/feature 分支并开始编写代码。为您的更改添加测试。
- 确保所有测试仍然通过:
phpunit
。 - 将更改推送到您的分支并提交新的 pull request。
有关更详细的指南和建议,请参阅CONTRIBUTING.md 文件。
许可
Baum 在MIT 许可证的条款下发布(有关详细信息,请参阅 LICENSE 文件)。
由 Estanislau Trepat (etrepat) 编码。我还在推特上@etrepat。