README

此包提供了一种特质，可以为Eloquent模型添加可排序行为。

新记录的排序列值由该模型所有记录的排序列的最大值加1确定。

该包还提供了一个查询范围，可以按正确顺序获取所有记录。

Spatie是比利时安特卫普的一家网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述在这里。

安装

此包可以通过Composer安装。

composer require spatie/eloquent-sortable

用法

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

1. 实现Spatie\EloquentSortable\Sortable接口。
2. 使用特质Spatie\EloquentSortable\SortableTrait。
3. 可选地指定用作排序列的列。默认为order_column。

示例

use Spatie\EloquentSortable\Sortable;
use Spatie\EloquentSortable\SortableTrait;

class MyModel extends Eloquent implements Sortable
{

    use SortableTrait;

    public $sortable = [
        'order_column_name' => 'order_column',
        'sort_when_creating' => true,
    ];
    
    ...
}

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

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

假设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
$orderedRecords = MyModel::ordered()->get(); 

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

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

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

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

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

/**
 * the record for model uuid '7a051131-d387-4276-bfda-e7c376099715' will have record_column value 1
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have record_column value 2
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have record_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 record_column value 10
 * the record for model uuid '40324562-c7ca-4c69-8018-aff81bff8c95' will have record_column value 11
 * the record for model uuid '5dc4d0f4-0c88-43a4-b293-7c7902a3cfd1' will have record_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::swapOrder($myModel, $anotherModel);

分组

如果您的模型/表有一个分组字段（通常是外键）：id, user_id, title, order_column并且您希望上述方法考虑这一点，您可以在您的模型中创建一个buildSortQuery方法

  public function buildSortQuery()
    {
        return static::query()->where('user_id', $this->user_id);
    }

这将限制计算仅限于模型实例的字段值。

测试

该包包含一些集成/烟雾测试，使用Orchestra设置。可以通过phpunit运行测试。

vendor/bin/phpunit

变更日志

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

贡献

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

安全

如果您发现任何与安全相关的问题，请通过电子邮件freek@spatie.be而不是使用问题跟踪器。

明信片软件

您可以使用此包，但如果它进入您的生产环境，我们非常希望您从您的家乡寄给我们一张明信片，提及您正在使用我们的哪些包。

我们的地址是：Spatie，Samberstraat 69D，2060 安特卫普，比利时。

我们将发布所有收到的明信片在我们的公司网站上。

鸣谢

• Freek Van der Herten
• 所有贡献者

替代方案

• Listify
• Rutorike-sortable

支持我们

Spatie是比利时安特卫普的一家网页设计公司。您可以在我们的网站上找到我们所有开源项目的概述在这里。

您的业务是否依赖于我们的贡献？通过 Patreon 来联系我们并支持我们。所有承诺都将用于分配人力进行维护和开发新酷炫功能。

许可证

MIT 许可证 (MIT)。更多详细信息，请参阅 许可证文件。