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'] فستقوم الحزمة تلقائيًا بتعيين أعلى رقم طلب لنموذج جديد؛
بافتراض أن جدول db لـ 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). يرجى الاطلاع على ملف الترخيص لمزيد من المعلومات.
