eloquent sortable
4.4.0
Este paquete proporciona un rasgo que agrega un comportamiento ordenable a un modelo Eloquent.
El valor de la columna de orden de un nuevo registro de un modelo está determinado por el valor máximo de la columna de orden de todos los registros de ese modelo + 1.
El paquete también proporciona un alcance de consulta para recuperar todos los registros en el orden correcto.
Spatie es una agencia de diseño web en Amberes, Bélgica. Encontrará una descripción general de todos nuestros proyectos de código abierto en nuestro sitio web.
Aprenda a crear un paquete como este viendo nuestro curso en vídeo premium:
Invertimos muchos recursos en la creación de los mejores paquetes de código abierto. Puedes apoyarnos comprando uno de nuestros productos pagos.
Agradecemos mucho que nos envíe una postal desde su ciudad natal, mencionando cuál de nuestros paquetes está utilizando. Encontrarás nuestra dirección en nuestra página de contacto. Publicamos todas las postales recibidas en nuestro muro virtual de postales.
Para Laravel 6.x o PHP 7.x, use la versión 3.x de este paquete.
Este paquete se puede instalar a través de Composer.
composer require spatie/eloquent-sortable
En Laravel 5.5 y superior, el proveedor de servicios se registrará automáticamente. En versiones anteriores del marco, simplemente agregue el proveedor de servicios en el archivo config/app.php :
' providers ' => [
...
Spatie EloquentSortable EloquentSortableServiceProvider::class,
];Opcionalmente puedes publicar el archivo de configuración con:
php artisan vendor:publish --tag=eloquent-sortable-config Este es el contenido del archivo que se publicará en 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 agregar un comportamiento ordenable a su modelo debe:
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 ,
];
// ...
} Si no establece un valor $sortable['order_column_name'] el paquete asumirá que el nombre de la columna de su pedido se llamará order_column .
Si no establece un valor $sortable['sort_when_creating'] el paquete asignará automáticamente el número de pedido más alto a un nuevo modelo;
Suponiendo que la tabla de base de datos de MyModel está vacía:
$ 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 (); Puede establecer un nuevo orden para todos los registros utilizando el 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, puede pasar el número de orden 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 );Puede modificar la consulta que se ejecutará pasando un cierre como cuarto 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 ordenar usando una columna que no sea la clave principal, use el 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 '
]); Al igual que con setNewOrder , setNewOrderByCustomColumn también aceptará un argumento de orden inicial opcional.
/**
* 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 );También puedes mover un modelo hacia arriba o hacia abajo con estos métodos:
$ myModel -> moveOrderDown ();
$ myModel -> moveOrderUp ();También puedes mover un modelo a la primera o última posición:
$ myModel -> moveToStart ();
$ myModel -> moveToEnd ();Puede determinar si un elemento es el primero o el último en orden:
$ myModel -> isFirstInOrder ();
$ myModel -> isLastInOrder ();Puedes intercambiar el orden de dos modelos:
MyModel:: swapOrder ( $ myModel , $ anotherModel ); Si su modelo/tabla tiene un campo de agrupación (generalmente una clave externa): id, user_id , title, order_column y desea que los métodos anteriores lo tengan en cuenta, puede crear un método buildSortQuery en su modelo:
// MyModel.php
public function buildSortQuery ()
{
return static :: query ()-> where ( ' user_id ' , $ this -> user_id );
}Esto restringirá los cálculos al valor de los campos de la instancia del modelo.
Una vez que se ha completado una clasificación, se envía un evento ( SpatieEloquentSortableEloquentModelSortedEvent ) que puedes escuchar. Esto puede resultar útil para ejecutar lógica de clasificación posterior, como borrar cachés u otras acciones que deben realizarse después de una clasificación.
El evento tiene un asistente isFor que le permite verificar cómodamente la clase Eloquent que se ha ordenado.
A continuación se muestra un ejemplo de cómo puede escuchar 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
}
}
}El paquete contiene algunas pruebas de integración/humo, configuradas con Orchestra. Las pruebas se pueden ejecutar a través de phpunit.
vendor/bin/phpunitConsulte CHANGELOG para obtener más información sobre los cambios recientes.
Consulte CONTRIBUCIÓN para obtener más detalles.
Revise nuestra política de seguridad sobre cómo informar vulnerabilidades de seguridad.
La Licencia MIT (MIT). Consulte el archivo de licencia para obtener más información.
