README

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

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

该包还提供了一种查询作用域，用于按正确顺序获取所有记录。

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

支持我们

通过观看我们的付费视频课程学习如何创建此类包

我们投入了大量资源来创建一流的开放源代码包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从您的家乡寄给我们明信片，说明您正在使用我们的哪个包。您可以在我们的联系我们页面上找到我们的地址。我们将发布所有收到的明信片在我们的虚拟明信片墙上。

安装

对于Laravel 6.x或PHP 7.x，请使用本包的3.x版本。

此包可以通过Composer安装。

composer require spatie/eloquent-sortable

在Laravel 5.5及以上版本中，服务提供者将自动注册。在框架的旧版本中，只需在config/app.php文件中添加服务提供者即可。

'providers' => [
    ...
    Spatie\EloquentSortable\EloquentSortableServiceProvider::class,
];

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

php artisan vendor:publish --tag=eloquent-sortable-config

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

return [
  /*
   * The name of the column that will be used to sort models.
   */
  '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,
];

用法

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

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

示例

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

class MyModel extends Model 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 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->isFirstInOrder();
$myModel->isLastInOrder();

您可以使用这些方法交换两个模型的顺序

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

分组

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

// MyModel.php

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

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

测试

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

vendor/bin/phpunit

变更日志

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

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

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

鸣谢

• Freek Van der Herten
• 所有贡献者

替代方案

• Listify
• Rutorike-sortable

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。