README

已弃用 - 请不要再使用！将不再更新。

Baum

从 gazsp/baum 分支 - 修复了数据库事务错误的关键问题。

修复了当同时运行多个 INSERT 或 DELETE 操作时，破坏嵌套集合的bug。

描述和重现都非常困难，但需要在重建树的同时运行的操作可能会遇到错误。

在修复bug之前，只有树的重建在事务内。实际的操作，例如 INSERT 或 DELETE 节点，不在事务内。

假设一个节点被删除，正在进行的重建... 然后几乎在同一个时间，第二个节点被删除，第二个重建因为表锁定而停止。之后树被破坏。

错误

应用程序日志显示以下错误。

SQLSTATE[40001]: Serialization failure: 1213 Deadlock found when trying to get lock; try restarting transaction

SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active.  Consider using PDOStatement::fetchAll().  Alternatively, if your code is only ever going to run against mysql, you may enable query buffering by setting the PDO::MYSQL_ATTR_USE_BUFFERED_QUERY attribute.

解决方案

我们通过在第一次写入数据库之前开始一个新的事务来解决它。我们还需要稍后提交这些事务。因此，我们在 Node 类中重写了 delete 和 finishSave 方法。

从 etrepat/baum 分支 - 继续开发并修复 Laravel 5.x 上的失败单元测试。

如果您发现一个bug，请提交问题，并提交一个带有失败单元测试的拉取请求。

Baum 是 Laravel 5 Eloquent ORM 的嵌套集合模式的实现。

对于 Laravel 4.2.x 兼容性，请检查 1.0.x 分支或使用最新的 1.0.x 标签版本。

关于嵌套集合

嵌套集合是一种智能方式来实现一个有序的树，允许进行快速、非递归查询。例如，您可以在单个查询中获取一个节点的所有后代，无论树有多深。缺点是插入/移动/删除需要复杂的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文件中添加以下内容将其添加到项目中

"dogado/baum": ">=1.3.0"

运行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:leaves()

你可能只对第一个根节点感兴趣

$firstRootNode = Category::root();

访问祖先/后代链

Baum提供了一些方法来访问嵌套集树中节点的前辈/后代链。要记住的主要事情是它们以两种方式提供

首先作为query scopes，返回一个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模型在节点在Nested Set树中每次移动时都会触发以下事件：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提供了一个简单的方法来提供Nested Set "范围"，这限制了我们将什么视为嵌套集树的一部分。这应该允许在同一数据库表中存在多个嵌套集树。

要使用范围功能，您可以在子类中重写scoped模型属性。此属性应包含一个数组，其中包含用于限制Nested Set查询的列名（数据库字段）

class Category extends Baum\Node {
  ...
  protected $scoped = array('company_id');
  ...
}

在先前的示例中，company_id有效地限制了（或“范围”）了Nested Set树。因此，对于该字段的每个值，我们可能能够构建一个完整的不同树。

$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

所有请求或遍历Nested Set树的方法都将使用scoped属性（如果提供）。

请注意，目前不支持在范围之间移动节点。

验证

::isValidNestedSet()静态方法允许您检查您的底层树结构是否正确。它主要检查以下3件事

检查绑定索引lft，rgt是否不为null，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时，请不要调用重建。

软删除

不建议使用软删除/restore()，如果软删除操作后修改了树，可能会导致问题。

播种/批量赋值

由于嵌套集结构通常涉及多个方法调用以构建层次结构（这将导致多个数据库查询），Baum提供了两个方便的方法，它们将映射提供的节点属性数组并从它们创建层次树

buildTree($nodeList)：(静态方法) 将提供的节点属性数组映射到数据库中。
makeTree($nodeList)：(实例方法) 使用当前节点实例作为父节点将提供的子树映射到数据库中。

这两个方法都会在主键未提供时创建新节点，如果提供了主键，则进行更新或创建，并删除所有不在影响作用域中的节点。请理解，buildTree静态方法的影响作用域是整个嵌套集树，而makeTree实例方法的影响作用域是当前节点实例的所有后代。

例如，假设我们想要将以下类别层次结构映射到我们的数据库中

电视 & 家庭影院
平板电脑 & 电子阅读器
计算机
- 笔记本电脑
  - PC笔记本电脑
  - Macbooks（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笔记本电脑
    - Macbooks（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 = ' ', $symbol = '');

一个示例用例

$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'
// );

贡献

考虑贡献吗？也许你发现了一些严重的错误？这真是个好消息！

分叉并克隆项目：git clone git@github.com:your-username/baum.git。
运行测试并确保它们在您的设置中通过：phpunit。
创建您的错误修复/功能分支并编写您的更改。为您的更改添加测试。
确保所有测试仍然通过：phpunit。
推送到您的分叉并提交新的pull请求。

请参阅CONTRIBUTING.md文件以获取更详细的指南和建议。

许可证

Baum遵循MIT许可证条款（详情请见LICENSE文件）。

由Estanislau Trepat (etrepat)编写。我还在twitter上@etrepat。

lshorz / baum

维护者

详细信息

README

Baum

从 gazsp/baum 分支 - 修复了数据库事务错误的关键问题。

从 etrepat/baum 分支 - 继续开发并修复 Laravel 5.x 上的失败单元测试。

文档

关于嵌套集合

背后的理论，简而言之

安装

入门

模型配置

迁移配置

用法

创建根节点

插入节点

删除节点

获取节点的嵌套级别

移动节点

向节点提问

关系

根和叶子作用域

访问祖先/后代链

限制返回的子级级别

自定义排序列

导出层次树

模型事件：`moving`和`moved`

作用域支持

验证

树重建

软删除

播种/批量赋值

其他/实用函数

节点提取查询作用域

获取嵌套列值列表

更多信息

贡献

许可证

lshorz / baum

维护者

详细信息

README

Baum

从 gazsp/baum 分支 - 修复了数据库事务错误的关键问题。

从 etrepat/baum 分支 - 继续开发并修复 Laravel 5.x 上的失败单元测试。

文档

关于嵌套集合

背后的理论，简而言之

安装

入门

模型配置

迁移配置

用法

创建根节点

插入节点

删除节点

获取节点的嵌套级别

移动节点

向节点提问

关系

根和叶子作用域

访问祖先/后代链

限制返回的子级级别

自定义排序列

导出层次树

模型事件：moving和moved

作用域支持

验证

树重建

软删除

播种/批量赋值

其他/实用函数

节点提取查询作用域

获取嵌套列值列表

更多信息

贡献

许可证

模型事件：`moving`和`moved`