‏laravel-query-builder v7.3.0: گروه‌بندی فیلترها با یک پارامتر

پکیج laravel-query-builder از اسپاتی یه ابزار محبوب لاراول برای فیلتر کردن کوئری‌ها از طریق query string URLه. مثلاً با تعریف AllowedFilter::partial('name')، درخواست به آدرس /users?filter[name]=john به‌صورت خودکار یه کوئری LIKE '%john%' اجرا می‌کنه. یه نکته مهم هم اینه که اگه کاربر سعی کنه روی فیلدی که مجاز نیست فیلتر بزنه، پکیج یه خطای InvalidFilterQuery با کد ۴۰۰ برمی‌گردونه.

مشکل قدیمی اینجا بود که وقتی می‌خواستی یه باکس جستجو داشته باشی که همزمان چند ستون رو بگرده، باید از AllowedFilter::callback استفاده می‌کردی. این روش یه تله پنهان داشت: اگه فراموش می‌کردی شرط‌های OR رو داخل یه closure مجزا بپیچی، عملگر OR اولویت پایین‌تری از AND داشت و کوئری نتایج اشتباه برمی‌گردوند — مثلاً کاربران غیرفعال هم توی نتایج می‌اومدن.

نسخه ۷.۳.۰ این مشکل رو با متد AllowedFilter::groupOr() حل کرده. کافیه فیلترها رو داخل یه آرایه بدی:

AllowedFilter::groupOr('q', [
    AllowedFilter::partial('name'),
    AllowedFilter::partial('email'),
])

با این تعریف، درخواست به /users?filter[q]=john یه کوئری درست تولید می‌کنه که شرط‌های OR داخل پرانتز محصور می‌شن:

WHERE (LOWER(name) LIKE '%john%' OR LOWER(email) LIKE '%john%')

وقتی این گروه رو با فیلترهای دیگه ترکیب کنی، مثلاً یه فیلتر status=active هم داشته باشی، پرانتزگذاری خودکار مطمئن می‌شه که OR داخل گروه هیچ‌وقت به AND بیرونی نشت نمی‌کنه. علاوه بر groupOr، متد groupAnd هم هست که همه اعضای گروه رو با AND به هم وصل می‌کنه.

این آپدیت کاملاً backward-compatible هست و هیچ تغییر شکننده‌ای نداره. اعضای گروه می‌تونن هر نوع AllowedFilter باشن و می‌شه چند گروه مستقل رو کنار هم تعریف کرد که هر کدوم scope جداگانه‌ای دارن و با AND به هم وصل می‌شن.

نکات کلیدی:

• نسخه ۷.۳.۰ پکیج laravel-query-builder اسپاتی منتشر شد
• متد جدید AllowedFilter::groupOr() چند فیلتر رو زیر یه پارامتر URL گروه‌بندی می‌کنه
• باگ کلاسیک اولویت OR/AND در جستجوی چندستونی رو به‌صورت خودکار مدیریت می‌کنه
• متد groupAnd هم برای گروه‌بندی با عملگر AND وجود داره
• آپدیت کاملاً non-breaking است