README

此包通过特质为 Eloquent 模型提供可排序行为。

此包基于 spatie/eloquent-sortable。请参阅 此处 了解为什么没有被合并。

功能

• 创建时自动排序
• 更新时自动排序
• 删除时自动排序
• 无限制列的分组

安装

您可以通过 Composer 安装此包。

composer require quadrubo/eloquent-autosort

您可以使用以下命令发布配置文件：

php artisan vendor:publish --tag="eloquent-autosort-config"

这是将发布到 config/eloquent-autosort.php 文件的文件内容

return [
    /*
     * Which column will be used as the order column.
     */
    'order_column_name' => 'order_column',

    /*
     * Define if the models should sort when creating.
     * When true, the package will automatically assign the highest order number to a new model.
     */
    'sort_when_creating' => true,

    /**
     * Define if the models should sort when updating.
     * When true, the package will automatically update the order of both the old and new group.
     */
    'sort_when_updating' => true,

    /**
     * Define if the models should sort when deleting.
     * When true, the package will fix the order within the current group when deleting.
     */
    'sort_when_deleting' => true,

    /**
     * Define the columns the model should be grouped by.
     * You can leave this empty and implement your own solution by overwriting
     * `buildSortQuery` and `hasChangedGroupAttributes`.
     */
    'groups' => [],
];

用法

要将可排序行为添加到您的模型中，您必须

1. 实现 Quadrubo\EloquentAutosort\Sortable 接口。
2. 使用特质 Quadrubo\EloquentAutosort\SortableTrait。

示例

use Quadrubo\EloquentSortable\Sortable;
use Quadrubo\EloquentSortable\SortableTrait;

class MyModel extends Model implements Sortable
{
    use SortableTrait;

    public $sortable = [
        'order_column_name' => 'order_column',
        'sort_when_creating' => true,
        'sort_when_updating' => true,
        'sort_when_deleting' => true,
        'groups' => [],
    ];

    // ...
}

如果您未设置值 $sortable['order_column_name']，则包将假设您的排序列名称为 order_column。

如果您未设置值 $sortable['sort_when_creating']，则包将自动为新模型分配最高的排序号。

如果您未设置值 $sortable['sort_when_updating']，则包将自动在更新时修复排序。

如果您未设置值 $sortable['sort_when_deleting']，则包将自动在删除时修复排序。

如果您未设置值 $sortable['groups']，则不会使用分组。

假设 MyModel 的数据库表为空

$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 1

$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 2

$myModel = new MyModel();
$myModel->save(); // order_column for this record will be set to 3


// the trait also provides the ordered query scope.
// note that when you use grouping, you should
// build the query first for this to be useful.
$orderedRecords = MyModel::ordered()->get();

您可以使用 setNewOrder-方法为所有记录设置新的顺序

/**
 * the record for model id 3 will have order_column value 1
 * the record for model id 1 will have order_column value 2
 * the record for model id 2 will have order_column value 3
 */
MyModel::setNewOrder([3,1,2]);

可选地，您可以传递起始顺序号作为第二个参数。

/**
 * the record for model id 3 will have order_column value 11
 * the record for model id 1 will have order_column value 12
 * the record for model id 2 will have order_column value 13
 */
MyModel::setNewOrder([3,1,2], 10);

要使用除主键之外的其他列进行排序，请使用 setNewOrderByCustomColumn-方法。

/**
 * the record for model uuid '7a051131-d387-4276-bfda-e7c376099715' will have order_column value 1
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have order_column value 2
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have order_column value 3
 */
MyModel::setNewOrderByCustomColumn('uuid', [
   '7a051131-d387-4276-bfda-e7c376099715',
   '40324562-c7ca-4c69-8018-aff81bff8c95',
   '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1'
]);

与 setNewOrder 类似，setNewOrderByCustomColumn 也会接受可选的起始顺序参数。

/**
 * the record for model uuid '7a051131-d387-4276-bfda-e7c376099715' will have order_column value 10
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have order_column value 11
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have order_column value 12
 */
MyModel::setNewOrderByCustomColumn('uuid', [
   '7a051131-d387-4276-bfda-e7c376099715',
   '40324562-c7ca-4c69-8018-aff81bff8c95',
   '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1'
], 10);

您还可以使用这些方法将模型向上或向下移动

$myModel->moveOrderDown();
$myModel->moveOrderUp();

您还可以将模型移动到第一个或最后一个位置

$myModel->moveToStart();
$myModel->moveToEnd();

您还可以将模型移动到特定或新位置

$myModel->moveToPosition(3);

// moves to a position using the value in your order_column attribute
$myModel->moveToNewPosition();

您还可以确定元素是否在顺序中是第一个或最后一个

$myModel->isFirstInOrder();
$myModel->isLastInOrder();

您还可以交换两个模型的顺序

MyModel::swapOrder($myModel, $anotherModel);

分组

如果您的模型/表有一个或多个分组字段（通常是一个外键）：id, user_id, title, order_column，并且您希望包将其考虑在内，您可以将分组字段添加到 $sortable['groups'] 数组中。

public $sortable = [
    'groups' => [
        'user_id',
    ],
];

这将限制计算到数组中的字段。

替换分组功能

如果您不喜欢分组功能的实现方式，您可以轻松地创建自己的功能。

1. 覆盖 buildSortQuery 方法以更改构建查询的行为。
2. 覆盖 hasChangedGroupAttributes 方法以提供一种方式让包知道何时应该重新排序。

测试

composer test

变更日志

请参阅 CHANGELOG 以获取有关最近更改的更多信息。

贡献

请参阅 CONTRIBUTING 以获取详细信息。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞。

致谢

• Quadrubo
• 所有贡献者

感谢Spatie/Eloquent-Sortable 团队为我们提供了基础包功能！

许可证

MIT 许可证（MIT）。更多信息请参阅许可证文件。