eloquent sortable
4.4.0
该包提供了一个向 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 ,
/*
* Define if the timestamps should be ignored when sorting.
* When true, updated_at will not be updated when using setNewOrder
*/
' ignore_timestamps ' => false ,
];要向模型添加可排序行为，您必须：
SpatieEloquentSortableSortable接口。SpatieEloquentSortableSortableTrait 。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 );您可以通过传递闭包作为第四个参数来修改将要执行的查询。
/**
* 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 , null , function ( $ query ) {
$ query -> withoutGlobalScope ( new ActiveScope );
});要使用主键以外的列进行排序，请使用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 );
}这会将计算限制为模型实例的字段值。
排序完成后，将调度一个您可以侦听的事件 ( SpatieEloquentSortableEloquentModelSortedEvent )。这对于运行排序后逻辑（例如清除缓存或排序后需要执行的其他操作）非常有用。
该事件有一个isFor帮助器，可以让您方便地检查已排序的 Eloquent 类。
以下是如何侦听此事件的示例：
use Spatie EloquentSortable EloquentModelSortedEvent as SortEvent ;
class SortingListener
{
public function handle ( SortEvent $ event ): void {
if ( $ event -> isFor (MyClass::class)) {
// ToDo: flush our cache
}
}
}该软件包包含一些使用 Orchestra 设置的集成/冒烟测试。测试可以通过 phpunit 运行。
vendor/bin/phpunit请参阅变更日志以了解有关最近更改内容的更多信息。
详细信息请参阅贡献。
请查看我们的安全政策，了解如何报告安全漏洞。
麻省理工学院许可证 (MIT)。请参阅许可证文件以获取更多信息。
