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)。請參閱許可證文件以獲取更多資訊。
