README

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

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

该包还提供了一个查询范围来获取所有记录的正确顺序。

安装

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

此包可以通过Composer安装。

composer require akas/eloquent-sortable

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

'providers' => [
    ...
    Akas\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. 实现Akas\EloquentSortable\Sortable接口。
2. 使用特质Akas\EloquentSortable\SortableTrait。
3. 可选地指定用作排序列的列。默认为order_column。

示例

use Akas\EloquentSortable\Sortable;
use Akas\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）。有关更多信息，请参阅许可文件。