‏Laravel Reorderable: مرتب‌سازی کشیدن و رها کردن برای مدل‌های Eloquent

پکیج Laravel Reorderable یه راه‌حل آماده‌ست برای اینکه بتونی آیتم‌های یه مدل Eloquent رو با کشیدن و رها کردن مرتب کنی و ترتیب جدید رو بدون نوشتن منطق اضافه توی دیتابیس ذخیره کنی. کافیه تریت HasSortOrder و قرارداد ReorderableContract رو روی مدلت اعمال کنی:

class Task extends Model implements ReorderableContract
{
    use HasSortOrder;

    protected $fillable = ['title', 'project_id', 'sort_order'];
    protected string $sortColumn = 'sort_order';

    public function getReorderLabel(): string
    {
        return $this->title;
    }
}

بعد از این، تریت خودش موقع ساخته شدن هر رکورد یه موقعیت ترتیبی بهش نسبت می‌ده و یه query scope به اسم ordered() هم اضافه می‌شه تا رکوردها همیشه به ترتیب درست واکشی بشن.

پکیج هم با Blade هم با Livewire کار می‌کنه. برای Blade کافیه یه @include ساده بزاری و برای Livewire از کامپوننت استفاده کنی. هر دو گزینه‌هایی مثل groupColumn و groupValue قبول می‌کنن که بهت اجازه می‌ده مرتب‌سازی رو فقط درون یه گروه خاص (مثلاً تسک‌های یه پروژه) محدود کنی. وقتی کاربر یه آیتم رو جابه‌جا می‌کنه، کامپوننت ترتیب جدید رو به مسیر POST /reorderable/update ارسال می‌کنه و دیتابیس آپدیت می‌شه.

اگه بخوای ترتیب‌دهی رو به‌صورت برنامه‌ای هم مدیریت کنی، متدهای moveToPosition() و reorderFromArray() در اختیارت هستن:

$task->moveToPosition(position: 2, groupColumn: 'project_id', groupValue: $task->project_id);

Task::reorderFromArray(orderedIds: [8, 3, 5, 1], groupColumn: 'project_id', groupValue: 12);

به جای اینکه همه چیز رو دستی تنظیم کنی، می‌تونی از دستور php artisan reorderable:make Task --table=tasks --label=title --column=sort_order استفاده کنی که خودش همه scaffold لازم رو می‌سازه. آپشن --label مشخص می‌کنه کدوم فیلد توی UI نمایش داده بشه و --column اسم ستون ترتیب رو تعیین می‌کنه.

برای امنیت، پکیج یه closure توی تنظیمات قبول می‌کنه تا دسترسی به روت آپدیت رو بتونی با Policy یا بررسی نقش کاربر کنترل کنی. بعد از هر مرتب‌سازی موفق هم رویداد ItemsReordered فایر می‌شه که اطلاعات کلاس مدل، آی‌دی‌های مرتب‌شده و داده‌های گروه رو حمل می‌کنه — مفید برای باطل کردن کش یا ثبت لاگ.

نکات کلیدی:

• با اعمال تریت HasSortOrder و ReorderableContract روی مدل فعال می‌شه
• کامپوننت‌های آماده Blade و Livewire با گزینه‌های یکسان ارائه می‌ده
• مرتب‌سازی رو می‌شه به یه گروه والد محدود کرد تا آیتم‌های پروژه‌های مختلف تداخل نداشته باشن
• دستور reorderable:make همه scaffold رو خودکار می‌سازه
• بعد از مرتب‌سازی رویداد ItemsReordered فایر می‌شه
• نیاز به PHP 8.3+، Laravel 13+ و Livewire 4+