README

Rinvex Categories 是一个多态 Laravel 包，用于分类管理。您可以使用它轻松地对任何 eloquent 模型进行分类，并利用嵌套集、Sluggable 和可翻译模型的力量。

安装

使用 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 进行自动 Slugging

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

管理您的可分类模型

API 是直观且非常直接的，所以让我们快速了解一下

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

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

// 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() 方法的签名完全相同，但具有附加功能：通过将 null 或空值传递给该方法，可以移除所有当前附加的分类：$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 作为结果。

同样，hasAllCategories() 方法与 hasAnyCategories() 方法具有完全相同的签名，但行为不同，它执行严格比较以检查是否附加了给定的所有分类。

高级用法

生成分类别名

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

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

注意：有关详细信息，请参阅 Sluggable 包。

智能参数检测

Rinvex 分类 方法可以接受分类列表，足够智能，可以处理几乎所有的输入，就像上面示例中看到的那样。它会检查输入类型并相应地处理。

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

你可能遇到需要获取特定分类下所有模型的情况，你可以轻松地按以下方式完成

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

查询范围

是的，Rinvex 分类 带有一些方便的查询范围，以下是一个使用示例

// 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;

注意：有关详细信息，请检查 可翻译 包。

插入分类

移动和插入分类涉及多个数据库查询，因此当分类被保存时，会自动开始事务。如果您与多个模型一起工作，可以使用全局事务。

另一个重要注意事项是，结构操作被延迟，直到你在模型上调用 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);

在指定分类之前或之后插入

您可以创建一个与 $neighbor 分类相邻的 $category。假设 $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);

后代可以预加载

$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();

从其他表中获取相关模型

想象一下，每个分类 有多个 产品。即建立了 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();

现在想象一下，每个分类 有多个 帖子。即这次建立了 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) 发布。

rogeecn / laravel-categories

维护者

详细信息