eloquent sortable
4.4.0
Este pacote fornece uma característica que adiciona comportamento classificável a um modelo Eloquent.
O valor da coluna de ordem de um novo registro de um modelo é determinado pelo valor máximo da coluna de ordem de todos os registros desse modelo + 1.
O pacote também fornece um escopo de consulta para buscar todos os registros na ordem correta.
Spatie é uma agência de webdesign em Antuérpia, Bélgica. Você encontrará uma visão geral de todos os nossos projetos de código aberto em nosso site.
Aprenda como criar um pacote como este assistindo nosso vídeo curso premium:
Investimos muitos recursos na criação dos melhores pacotes de código aberto. Você pode nos apoiar comprando um de nossos produtos pagos.
Agradecemos muito que você nos envie um cartão postal de sua cidade natal, mencionando qual(is) de nossos pacotes você está usando. Você encontrará nosso endereço em nossa página de contato. Publicamos todos os cartões postais recebidos em nosso mural virtual de cartões postais.
Para Laravel 6.x ou PHP 7.x, use a versão 3.x deste pacote.
Este pacote pode ser instalado através do Composer.
composer require spatie/eloquent-sortable
No Laravel 5.5 e superior o provedor de serviços será registrado automaticamente. Em versões mais antigas do framework basta adicionar o provedor de serviços no arquivo config/app.php :
' providers ' => [
...
Spatie EloquentSortable EloquentSortableServiceProvider::class,
];Opcionalmente, você pode publicar o arquivo de configuração com:
php artisan vendor:publish --tag=eloquent-sortable-config Este é o conteúdo do arquivo que será publicado em 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 ,
];Para adicionar comportamento classificável ao seu modelo, você deve:
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 ,
];
// ...
} Se você não definir um valor $sortable['order_column_name'] o pacote assumirá que o nome da coluna do seu pedido será nomeado order_column .
Se você não definir um valor $sortable['sort_when_creating'] o pacote atribuirá automaticamente o maior número de pedido a um novo modelo;
Supondo que a tabela db para MyModel esteja vazia:
$ 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 (); Você pode definir uma nova ordem para todos os registros usando o método 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 ]);Opcionalmente você pode passar o número da ordem inicial como segundo argumento.
/**
* 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 );Você pode modificar a consulta que será executada passando um encerramento como quarto argumento.
/**
* 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 );
}); Para classificar usando uma coluna diferente da chave primária, use o método 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 '
]); Tal como acontece com setNewOrder , setNewOrderByCustomColumn também aceitará um argumento opcional de ordem inicial.
/**
* 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 );Você também pode mover um modelo para cima ou para baixo com estes métodos:
$ myModel -> moveOrderDown ();
$ myModel -> moveOrderUp ();Você também pode mover um modelo para a primeira ou última posição:
$ myModel -> moveToStart ();
$ myModel -> moveToEnd ();Você pode determinar se um elemento é o primeiro ou o último na ordem:
$ myModel -> isFirstInOrder ();
$ myModel -> isLastInOrder ();Você pode trocar a ordem de dois modelos:
MyModel:: swapOrder ( $ myModel , $ anotherModel ); Se o seu modelo/tabela tiver um campo de agrupamento (geralmente uma chave estrangeira): id, user_id , title, order_column e você quiser que os métodos acima levem isso em consideração, você pode criar um método buildSortQuery no seu modelo:
// MyModel.php
public function buildSortQuery ()
{
return static :: query ()-> where ( ' user_id ' , $ this -> user_id );
}Isso restringirá os cálculos aos valores dos campos da instância do modelo.
Depois que uma classificação for concluída, um evento ( SpatieEloquentSortableEloquentModelSortedEvent ) será enviado e você poderá ouvi-lo. Isso pode ser útil para executar a lógica pós-classificação, como limpar caches ou outras ações que precisam ser executadas após uma classificação.
O evento possui um auxiliar isFor que permite verificar convenientemente a classe Eloquent que foi classificada.
Abaixo está um exemplo de como você pode ouvir este evento:
use Spatie EloquentSortable EloquentModelSortedEvent as SortEvent ;
class SortingListener
{
public function handle ( SortEvent $ event ): void {
if ( $ event -> isFor (MyClass::class)) {
// ToDo: flush our cache
}
}
}O pacote contém alguns testes de integração/smoke, configurados com Orchestra. Os testes podem ser executados via phpunit.
vendor/bin/phpunitConsulte CHANGELOG para obter mais informações sobre o que mudou recentemente.
Consulte CONTRIBUINDO para obter detalhes.
Revise nossa política de segurança sobre como relatar vulnerabilidades de segurança.
A licença MIT (MIT). Consulte Arquivo de licença para obter mais informações.
