README

Rinvex Categories 是一个用于分类管理的多态 Laravel 扩展包。您可以轻松地对任何 eloquent 模型进行分类，并利用 Nested Sets、Sluggable 和 Translatable 模型的功能。

安装

通过 composer 安装包

composer require rinvex/laravel-categories

发布资源（迁移和配置文件）
```
php artisan rinvex:publish:categories
```
执行以下命令执行迁移
```
php artisan rinvex:migrate:categories
```
完成！

使用方法

要为 eloquent 模型添加分类支持，请使用 \Rinvex\Categories\Traits\Categorizable 特性。

管理您的分类

您的分类只是普通的 eloquent 模型，因此您可以像这样处理它。这里没有什么特别之处！

注意：由于 Rinvex Categories 扩展和利用了其他出色的包，请查看以下文档以获取更多详细信息

使用 kalnoy/nestedset 强大的嵌套集

使用 spatie/laravel-sluggable 自动生成缩写

使用 spatie/laravel-translatable 开箱即用的可翻译

管理您的可分类模型

API 直观且简单易懂，让我们快速看一下

// Get all categories
$allCategories = app('rinvex.categories.category')->all();

// Get instance of your model
$post = new \App\Models\Post::find(123);

// Get attached categories collection
$post->categories;

// Get attached categories query builder
$post->categories();

您可以通过多种方式添加分类

// Single category id
$post->attachCategories(1);

// Multiple category IDs array
$post->attachCategories([1, 2, 5]);

// Multiple category IDs collection
$post->attachCategories(collect([1, 2, 5]));

// Single category model instance
$categoryInstance = app('rinvex.categories.category')->first();
$post->attachCategories($categoryInstance);

// Single category slug
$post->attachCategories('test-category');

// Multiple category slugs array
$post->attachCategories(['first-category', 'second-category']);

// Multiple category slugs collection
$post->attachCategories(collect(['first-category', 'second-category']));

// Multiple category model instances
$categoryInstances = app('rinvex.categories.category')->whereIn('id', [1, 2, 5])->get();
$post->attachCategories($categoryInstances);

注意

使用 attachCategories() 方法将给定的分类附加到模型，而不触及当前附加的分类，而 syncCategories() 方法可以取消任何不在给定项中的记录，此方法接受一个可选的布尔参数，将其设置为 true 或 false 作为取消标记。

要取消模型分类，可以使用 detachCategories() 方法，该方法与 attachCategories() 方法具有相同的签名，具有附加所有当前附加分类的功能，如下所示：$post->detachCategories();。

正如您所预期的，您还可以检查分类是否已附加

// Single category id
$post->hasAnyCategories(1);

// Multiple category IDs array
$post->hasAnyCategories([1, 2, 5]);

// Multiple category IDs collection
$post->hasAnyCategories(collect([1, 2, 5]));

// Single category model instance
$categoryInstance = app('rinvex.categories.category')->first();
$post->hasAnyCategories($categoryInstance);

// Single category slug
$post->hasAnyCategories('test-category');

// Multiple category slugs array
$post->hasAnyCategories(['first-category', 'second-category']);

// Multiple category slugs collection
$post->hasAnyCategories(collect(['first-category', 'second-category']));

// Multiple category model instances
$categoryInstances = app('rinvex.categories.category')->whereIn('id', [1, 2, 5])->get();
$post->hasAnyCategories($categoryInstances);

注意

使用 hasAnyCategories() 方法检查模型是否已附加任何给定分类。它返回布尔值 true 或 false。

类似地，使用与 hasAnyCategories() 方法相同的签名，但行为不同，并执行严格的比较以检查是否已附加所有给定分类的 hasAllCategories() 方法。

高级用法

生成分类缩写

Rinvex Categories 自动生成缩写并自动检测和插入默认翻译（如果未提供），但您仍然可以通过正常的 eloquent create 方法显式传递它，如下所示：

app('rinvex.categories.category')->create(['name' => ['en' => 'My New Category'], 'slug' => 'custom-category-slug']);

注意：查看 Sluggable 包以获取更多详细信息。

智能参数检测

Rinvex Categories 方法可以接受分类列表，它们足够智能，可以处理几乎所有类型的输入，如上面示例中所示。它会检查输入类型并根据情况进行处理。

检索所有与分类关联的模型

您可能会遇到需要获取与某些分类关联的所有模型的情况，您可以通过以下方式轻松地做到这一点：

$category = app('rinvex.categories.category')->find(1);
$category->entries(\App\Models\Post::class)->get();

查询作用域

是的，Rinvex Categories 随带了一些方便的查询作用域，以下为使用示例

// Single category id
$post->withAnyCategories(1)->get();

// Multiple category IDs array
$post->withAnyCategories([1, 2, 5])->get();

// Multiple category IDs collection
$post->withAnyCategories(collect([1, 2, 5]))->get();

// Single category model instance
$categoryInstance = app('rinvex.categories.category')->first();
$post->withAnyCategories($categoryInstance)->get();

// Single category slug
$post->withAnyCategories('test-category')->get();

// Multiple category slugs array
$post->withAnyCategories(['first-category', 'second-category'])->get();

// Multiple category slugs collection
$post->withAnyCategories(collect(['first-category', 'second-category']))->get();

// Multiple category model instances
$categoryInstances = app('rinvex.categories.category')->whereIn('id', [1, 2, 5])->get();
$post->withAnyCategories($categoryInstances)->get();

注意

withAnyCategories() 作用域用于查找具有给定分类的任何关联分类的文章。它通常返回一个查询构建器，因此您可以将其链式调用或调用 get() 方法来执行并获取结果。

类似地，还有其他一些作用域，如 withAllCategories()，用于查找具有给定所有关联分类的文章，withoutCategories() 用于查找没有给定任何关联分类的文章，最后是 withoutAnyCategories()，用于查找没有任何关联分类的文章。所有作用域都是平等创建的，具有相同的签名，并返回查询构建器。

分类翻译

如下轻松管理分类翻译：

$category = app('rinvex.categories.category')->find(1);

// Update title translations
$category->setTranslation('name', 'en', 'New English Category Title')->save();

// Alternatively you can use default eloquent update
$category->update([
    'name' => [
        'en' => 'New Category',
        'ar' => 'تصنيف جديد',
    ],
]);

// Get single category translation
$category->getTranslation('name', 'en');

// Get all category translations
$category->getTranslations('name');

// Get category title in default locale
$category->name;

注意：查看 Translatable 包以获取更多详细信息。

插入分类

移动和插入分类涉及多个数据库查询，因此当分类保存时，会自动开始事务。如果您正在处理多个模型，则可以使用全局事务。

另一个重要的注意事项是，结构操作被延迟，直到您在模型上调用 save（一些方法隐式调用 save 并返回操作的成功布尔结果）。

如果模型成功保存，并不意味着分类已经移动。如果您的应用程序依赖于分类是否实际改变了位置，请使用 hasMoved 方法。

if ($category->save()) {
    $moved = $category->hasMoved();
}

创建分类

当您简单创建一个分类时，它将被追加到树的末尾

app('rinvex.categories.category')->create($attributes); // Saved as root

$category = app('rinvex.categories.category')->fill($attributes);
$category->save(); // Saved as root

在这种情况下，该分类被认为是 根分类，这意味着它没有父分类。

从现有分类创建根分类

分类将被追加到树的末尾

// #1 Implicit save
$category->saveAsRoot();

// #2 Explicit save
$category->makeRoot()->save();

追加和前置到指定的父分类

如果您想将分类作为其他分类的子分类，您可以将其作为最后一个或第一个子分类。假设 $parent 是某个现有分类，有以下几种方法可以追加一个分类：

// #1 Using deferred insert
$category->appendToNode($parent)->save();

// #2 Using parent category
$parent->appendNode($category);

// #3 Using parent's children relationship
$parent->children()->create($attributes);

// #5 Using category's parent relationship
$category->parent()->associate($parent)->save();

// #6 Using the parent attribute
$category->parent_id = $parent->getKey();
$category->save();

// #7 Using static method
app('rinvex.categories.category')->create($attributes, $parent);

并且只有几种方法可以前置

// #1 Using deferred insert
$category->prependToNode($parent)->save();

// #2 Using parent category
$parent->prependNode($category);

在指定的分类前或后插入

您可以将 $category 作为 $neighbor 分类的一个邻居。假设 $neighbor 是某个现有分类，而目标分类可以是新的。如果目标分类存在，它将被移动到新位置，并且如果需要，父分类将改变。

# Explicit save
$category->afterNode($neighbor)->save();
$category->beforeNode($neighbor)->save();

# Implicit save
$category->insertAfterNode($neighbor);
$category->insertBeforeNode($neighbor);

从数组构建树

当在分类上使用静态方法 create 时，它会检查属性中是否包含 children 键。如果包含，它将递归地创建更多分类，如下所示：

$category = app('rinvex.categories.category')->create([
    'name' => [
        'en' => 'New Category Title',
    ],

    'children' => [
        [
            'name' => 'Bar',

            'children' => [
                [ 'name' => 'Baz' ],
            ],
        ],
    ],
]);

$category->children 现在包含已创建的子分类列表。

从数组重新构建树

您可以轻松重建一棵树。这对于大量更改树的结构非常有用。给定一个分类数组 $data，您可以按照以下方式构建树：

$data = [
    [ 'id' => 1, 'name' => 'foo', 'children' => [ ... ] ],
    [ 'name' => 'bar' ],
];

app('rinvex.categories.category')->rebuildTree($data, $delete);

对于标题为 foo 的分类，指定了 id，这意味着现有的分类将被填充并保存。如果分类不存在，将抛出 ModelNotFoundException。此外，该分类还指定了 children，它也是一个分类数组；它们将以相同的方式处理并保存为 foo 分类下的子分类。

分类 bar 没有指定主键，因此它将被视为新分类，并创建。

$delete 表示是否删除存在于 $data 中但不在其内的分类。默认情况下，不会删除分类。

检索分类

在某些情况下，我们将使用一个 $id 变量，它是目标分类的 id。

祖先

祖先形成了一个到分类的父级链。这对于显示当前分类的面包屑非常有用。

// #1 Using accessor
$result = $category->getAncestors();

// #2 Using a query
$result = $category->ancestors()->get();

// #3 Getting ancestors by primary key
$result = app('rinvex.categories.category')->ancestorsOf($id);

后代

后代是指子树中的所有分类，即分类的子分类，子分类的子分类等。

// #1 Using relationship
$result = $category->descendants;

// #2 Using a query
$result = $category->descendants()->get();

// #3 Getting descendants by primary key
$result = app('rinvex.categories.category')->descendantsOf($id);

// #3 Get descendants and the category by id
$result = app('rinvex.categories.category')->descendantsAndSelf($id);

后代可以被 eager 加载。

$categories = app('rinvex.categories.category')->with('descendants')->whereIn('id', $idList)->get();

兄弟

兄弟是指具有相同父级的分类。

$result = $category->getSiblings();

$result = $category->siblings()->get();

仅获取下一个兄弟分类。

// Get a sibling that is immediately after the category
$result = $category->getNextSibling();

// Get all siblings that are after the category
$result = $category->getNextSiblings();

// Get all siblings using a query
$result = $category->nextSiblings()->get();

获取上一个兄弟分类。

// Get a sibling that is immediately before the category
$result = $category->getPrevSibling();

// Get all siblings that are before the category
$result = $category->getPrevSiblings();

// Get all siblings using a query
$result = $category->prevSiblings()->get();

从其他表获取相关模型

想象一下，每个分类 has many 产品。即建立了 HasMany 关系。如何获取 $category 和其所有后代的全部产品？很简单！

// Get ids of descendants
$categories = $category->descendants()->pluck('id');

// Include the id of category itself
$categories[] = $category->getKey();

// Get products
$goods = Product::whereIn('category_id', $categories)->get();

现在想象一下，每个分类 has many 帖子。即这次建立了 morphToMany 关系。如何获取 $category 和其所有后代的全部帖子？这可能吗？当然可以！

// Get ids of descendants
$categories = $category->descendants()->pluck('id');

// Include the id of category itself
$categories[] = $category->getKey();

// Get posts
$posts = \App\Models\Post::withCategories($categories)->get();

包括分类深度

如果您需要知道分类处于哪个级别

$result = app('rinvex.categories.category')->withDepth()->find($id);

$depth = $result->depth;

根分类将位于级别 0。根分类的子分类将具有级别 1，依此类推。要获取指定级别的分类，您可以在查询构建器上应用 having 约束

$result = app('rinvex.categories.category')->withDepth()->having('depth', '=', 1)->get();

默认排序

每个分类都有一个唯一的 _lft 值，该值决定了其在树中的位置。如果您想按此值对分类进行排序，您可以使用查询构建器上的 defaultOrder 方法

// All categories will now be ordered by lft value
$result = app('rinvex.categories.category')->defaultOrder()->get();

您可以按相反的顺序获取分类。

$result = app('rinvex.categories.category')->reversed()->get();

移动分类

向上或向下移动分类以影响默认顺序。

$bool = $category->down();
$bool = $category->up();

// Shift category by 3 siblings
$bool = $category->down(3);

操作的结果是布尔值，表示分类是否已更改其位置。

约束

可以应用于查询构建器的各种约束

whereIsRoot() 以获取仅根分类；
whereIsAfter($id) 以获取指定 id 分类之后的每个分类（而不仅仅是兄弟分类）；
whereIsBefore($id) 以获取在指定 id 分类之前的每个分类。

后代约束

$result = app('rinvex.categories.category')->whereDescendantOf($category)->get();
$result = app('rinvex.categories.category')->whereNotDescendantOf($category)->get();
$result = app('rinvex.categories.category')->orWhereDescendantOf($category)->get();
$result = app('rinvex.categories.category')->orWhereNotDescendantOf($category)->get();

// Include target category into result set
$result = app('rinvex.categories.category')->whereDescendantOrSelf($category)->get();

祖先约束

$result = app('rinvex.categories.category')->whereAncestorOf($category)->get();

$category 可以是模型的主键或模型实例。

构建树

在获取一系列分类后，您可以将它们转换为树。例如

$tree = app('rinvex.categories.category')->get()->toTree();

这将填充集合中每个分类的 parent 和 children 关系，您可以使用递归算法渲染树

$categories = app('rinvex.categories.category')->get()->toTree();

$traverse = function ($categories, $prefix = '-') use (&$traverse) {
    foreach ($categories as $category) {
        echo PHP_EOL.$prefix.' '.$category->name;

        $traverse($category->children, $prefix.'-');
    }
};

$traverse($categories);

这将输出如下内容

- Root
-- Child 1
--- Sub child 1
-- Child 2
- Another root

构建扁平树

此外，您还可以构建一个扁平树：一个分类列表，其中子分类紧跟在父分类之后。这在您获取具有自定义排序（例如字母顺序）的分类且不想使用递归遍历分类时非常有用。

$categories = app('rinvex.categories.category')->get()->toFlatTree();

获取子树

有时您不需要加载整个树，只需要特定分类的子树

$root = app('rinvex.categories.category')->find($rootId);
$tree = $root->descendants->toTree($root);

现在 $tree 包含 $root 分类下的子分类。

如果您不需要 $root 分类本身，请执行以下操作

$tree = app('rinvex.categories.category')->descendantsOf($rootId)->toTree($rootId);

删除分类

要删除分类

$category->delete();

重要！分类的任何后代也将被删除！

重要！必须将分类作为模型进行删除，不要尝试使用如下查询进行删除

app('rinvex.categories.category')->where('id', '=', $id)->delete();

这将破坏树！

辅助方法

// Check if category is a descendant of other category
$bool = $category->isDescendantOf($parent);

// Check whether the category is a root:
$bool = $category->isRoot();

// Other checks
$category->isChildOf($other);
$category->isAncestorOf($other);
$category->isSiblingOf($other);

检查一致性

您可以检查树是否已损坏（即存在某些结构错误）

// Check if tree is broken
$bool = app('rinvex.categories.category')->isBroken();

// Get tree error statistics
$data = app('rinvex.categories.category')->countErrors();

树错误统计将返回包含以下键的数组

oddness -- 拥有错误lft和rgt值的分类数量
duplicates -- 拥有相同lft或rgt值的分类数量
wrong_parent -- 拥有无效parent_id值且与lft和rgt值不对应的分类数量
missing_parent -- 指向不存在分类的parent_id的分类数量

修复树

如果分类树已损坏，现在可以修复。使用parent_id列的继承信息，为每个分类设置正确的_lft和_rgt值。

app('rinvex.categories.category')->fixTree();

注意：有关详细信息，请参阅Nested Sets软件包。

变更日志

请参阅变更日志以了解项目的完整历史。

支持

以下支持渠道尽在您的指尖

贡献与协议

感谢您考虑为该项目做出贡献！贡献指南可在CONTRIBUTING.md中找到。

欢迎提出错误报告、功能请求和拉取请求。

安全漏洞

我们希望确保此软件包对每个人都安全。如果您在此软件包中发现安全漏洞，我们感谢您以负责任的方式向我们披露。

公开披露漏洞可能会使整个社区面临风险。如果您发现安全问题，请通过help@rinvex.com发送电子邮件给我们。我们将与您合作，确保我们了解问题的范围，并全面解决您的问题。我们将把发送到help@rinvex.com的邮件视为最高优先级，并尽快解决任何问题。

在纠正安全漏洞后，将尽快部署安全热修复版本。

关于Rinvex

Rinvex是一家成立于2016年6月的开罗，埃及的软件解决方案初创公司，专注于为中小企业提供集成企业解决方案。我们相信，我们的动力是“价值、影响力和影响力”，这是我们与众不同的地方，通过软件的力量释放我们哲学的无尽可能性。我们喜欢称之为“以生活速度的创新”。这就是我们如何为推进人类文明做出我们的贡献。

许可证

此软件根据MIT许可证（MIT）发布。

（c）2016-2022 Rinvex LLC，部分权利保留。

rinvex / laravel-categories

维护者

详细信息