akemys/baum

Baum 是 Eloquent 模型的嵌套集模式实现。

维护者

详细信息

github.com/akemys/baum

源代码

问题

安装: 25

依赖: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

开放问题: 0

1.0.1 2023-06-08 07:41 UTC

Requires

Requires (Dev)

MIT 58ecf3566cea54e741e172b38e9ae8c423141a6b

databaselaravelnested seteloquentLaravel 4laravel 5

This package is auto-updated.

Last update: 2024-09-29 04:49:51 UTC

README

Build Status

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

为了与 Laravel 4.2.x 兼容，请检查 1.0.x 分支 或使用最新的 1.0.x 标签发布。

文档

关于嵌套集

嵌套集是一种智能的方式来实现一个有序的树，它允许快速的非递归查询。例如，你可以一次性查询到一个节点的所有后代，无论树的深度如何。缺点是插入/移动/删除需要复杂的 SQL，但这个包会在幕后处理这一切！

嵌套集适用于有序树（例如菜单、商品类别）以及需要高效查询的大树（例如线程帖子）。

有关嵌套集的更多信息，请参阅 维基百科条目。此外，这是一篇很好的入门教程：[http://www.evanpetersen.com/item/nested-sets.html](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：对父节点的引用（int）
  • 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与您的模型一起使用了。下面是一些示例。

创建根节点

默认情况下，所有节点都创建为根节点

$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()静态方法允许您检查您的底层树结构是否正确。它主要检查以下三件事：

  • 检查约束索引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

贡献

想要贡献吗？也许你发现了一些讨厌的虫子？这是个好消息！

  1. 分叉并克隆项目： git clone git@github.com:your-username/baum.git。
  2. 运行测试并确保它们通过你的设置： phpunit。
  3. 创建你的 bugfix/feature 分支，并开始编写你的更改。为你的更改添加测试。
  4. 确保所有测试仍然通过： phpunit。
  5. 将你的分叉推送到你的 fork 并提交新的 pull request。

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

许可协议

Baum 在 MIT 许可协议 的条款下进行许可（有关详细信息，请参阅 LICENSE 文件）。

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