eloquent sortable
4.4.0
Ce package fournit un trait qui ajoute un comportement triable à un modèle Eloquent.
La valeur de la colonne de commande d'un nouvel enregistrement d'un modèle est déterminée par la valeur maximale de la colonne de commande de tous les enregistrements de ce modèle + 1.
Le package fournit également une portée de requête pour récupérer tous les enregistrements dans le bon ordre.
Spatie est une agence de webdesign à Anvers, en Belgique. Vous trouverez un aperçu de tous nos projets open source sur notre site Internet.
Apprenez à créer un package comme celui-ci en regardant notre cours vidéo premium :
Nous investissons beaucoup de ressources dans la création des meilleurs packages open source de leur catégorie. Vous pouvez nous soutenir en achetant l'un de nos produits payants.
Nous apprécions grandement que vous nous envoyiez une carte postale de votre ville natale, mentionnant le(s) forfait(s) que vous utilisez. Vous trouverez notre adresse sur notre page contact. Nous publions toutes les cartes postales reçues sur notre mur virtuel de cartes postales.
Pour Laravel 6.x ou PHP 7.x, utilisez la version 3.x de ce package.
Ce package peut être installé via Composer.
composer require spatie/eloquent-sortable
Dans Laravel 5.5 et supérieur, le fournisseur de services sera automatiquement enregistré. Dans les anciennes versions du framework, ajoutez simplement le fournisseur de services dans le fichier config/app.php :
' providers ' => [
...
Spatie EloquentSortable EloquentSortableServiceProvider::class,
];Vous pouvez éventuellement publier le fichier de configuration avec :
php artisan vendor:publish --tag=eloquent-sortable-config C'est le contenu du fichier qui sera publié dans 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 ,
];Pour ajouter un comportement triable à votre modèle, vous devez :
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 vous ne définissez pas de valeur $sortable['order_column_name'] le package supposera que le nom de votre colonne de commande sera nommé order_column .
Si vous ne définissez pas de valeur $sortable['sort_when_creating'] le package attribuera automatiquement le numéro de commande le plus élevé à un nouveau modèle ;
En supposant que la table de base de données de MyModel est vide :
$ 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 (); Vous pouvez définir un nouvel ordre pour tous les enregistrements à l'aide de la méthode 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 ]);Vous pouvez éventuellement transmettre le numéro de commande de départ comme deuxième argument.
/**
* 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 );Vous pouvez modifier la requête qui sera exécutée en passant une fermeture comme quatrième argument.
/**
* 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 );
}); Pour trier à l’aide d’une colonne autre que la clé primaire, utilisez la méthode 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 '
]); Comme avec setNewOrder , setNewOrderByCustomColumn acceptera également un argument facultatif d’ordre de départ.
/**
* 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 );Vous pouvez également déplacer un modèle vers le haut ou vers le bas avec ces méthodes :
$ myModel -> moveOrderDown ();
$ myModel -> moveOrderUp ();Vous pouvez également déplacer un modèle vers la première ou la dernière position :
$ myModel -> moveToStart ();
$ myModel -> moveToEnd ();Vous pouvez déterminer si un élément est premier ou dernier dans l'ordre :
$ myModel -> isFirstInOrder ();
$ myModel -> isLastInOrder ();Vous pouvez intervertir l'ordre de deux modèles :
MyModel:: swapOrder ( $ myModel , $ anotherModel ); Si votre modèle/table a un champ de regroupement (généralement une clé étrangère) : id, user_id , title, order_column et que vous souhaitez que les méthodes ci-dessus en tiennent compte, vous pouvez créer une méthode buildSortQuery sur votre modèle :
// MyModel.php
public function buildSortQuery ()
{
return static :: query ()-> where ( ' user_id ' , $ this -> user_id );
}Cela limitera les calculs à la valeur des champs de l'instance de modèle.
Une fois le tri terminé, un événement ( SpatieEloquentSortableEloquentModelSortedEvent ) est distribué et vous pouvez l'écouter. Cela peut être utile pour exécuter une logique de post-tri telle que la suppression des caches ou d'autres actions qui doivent être effectuées après un tri.
L'événement dispose d'un assistant isFor qui vous permet de vérifier facilement la classe Eloquent qui a été triée.
Vous trouverez ci-dessous un exemple de la façon dont vous pouvez écouter cet événement :
use Spatie EloquentSortable EloquentModelSortedEvent as SortEvent ;
class SortingListener
{
public function handle ( SortEvent $ event ): void {
if ( $ event -> isFor (MyClass::class)) {
// ToDo: flush our cache
}
}
}Le package contient des tests d'intégration/de fumée, mis en place avec Orchestra. Les tests peuvent être exécutés via phpunit.
vendor/bin/phpunitVeuillez consulter CHANGELOG pour plus d'informations sur ce qui a changé récemment.
Veuillez consulter CONTRIBUER pour plus de détails.
Veuillez consulter notre politique de sécurité pour savoir comment signaler les vulnérabilités de sécurité.
La licence MIT (MIT). Veuillez consulter le fichier de licence pour plus d'informations.
