پرش به مطلب اصلی

Boolean Scopes

Boolean Scopes سیستمی برای تولید خودکار ماکروهای Query Builder بر اساس فیلدهای boolean در پروژه است.

با استفاده از این سیستم می‌توان به‌جای استفاده تکراری از ()where برای فیلدهای boolean، از ماکروهای روان و خواناتر استفاده کرد:

  • فیلتر کردن رکوردهای فعال / غیرفعال
  • فیلتر کردن بر اساس وضعیت تأیید، انقضا، آرشیو و غیره
  • افزودن فیلدهای سفارشی از طریق کانفیگ
  • تولید خودکار ماکروها هنگام بوت شدن اپلیکیشن

قابلیت‌ها​

تولید خودکار ماکرو​

به ازای هر فیلد boolean، دو ماکرو به‌صورت خودکار روی Eloquent Builder ثبت می‌شود:

  • ()onlyFieldName — فیلتر جایی که فیلد برابر 1 است
  • ()exceptFieldName — فیلتر جایی که فیلد برابر 0 است

قابل گسترش از طریق کانفیگ​

فیلدهای جدید می‌توانند بدون تغییر کد اصلی، از فایل کانفیگ dornica-app.php اضافه شوند.

حذف تکراری خودکار​

فیلدهای تکراری میان لیست پیش‌فرض و لیست کانفیگ، به‌صورت خودکار حذف می‌شوند.

اعتبارسنجی کانفیگ​

در صورت نامعتبر بودن کانفیگ، پیش از اجرا InvalidBooleanScopeFieldsTypeException پرتاب می‌شود.

فیلدهای پیش‌فرض​

سیستم به‌صورت پیش‌فرض برای فیلدهای زیر ماکرو تولید می‌کند:

فیلدماکروی onlyماکروی except
is_archive()onlyIsArchive()exceptIsArchive
is_started()onlyIsStarted()exceptIsStarted
is_success()onlyIsSuccess()exceptIsSuccess
is_verified()onlyIsVerified()exceptIsVerified
is_expired()onlyIsExpired()exceptIsExpired
is_active()onlyIsActive()exceptIsActive
is_archived()onlyIsArchived()exceptIsArchived
is_count()onlyIsCount()exceptIsCount
is_default()onlyIsDefault()exceptIsDefault
is_end()onlyIsEnd()exceptIsEnd
is_lock()onlyIsLock()exceptIsLock
is_required()onlyIsRequired()exceptIsRequired

استفاده از ماکروها​

فیلتر ساده​

// فقط کاربران فعال
User::onlyIsActive()->get();

// کاربران غیرفعال
User::exceptIsActive()->get();

زنجیر کردن چند ماکرو​

User::onlyIsActive()
    ->exceptIsExpired()
    ->onlyIsVerified()
    ->get();

استفاده درون Relationship​

Post::with(['comments' => function ($q) {
    $q->onlyIsActive();
}])->get();

افزودن فیلدهای سفارشی​

از طریق کانفیگ​

فیلدهای اضافی را در فایل config/dornica-app.php تعریف کنید:

return [
    'additional_boolean_scope_fields' => [
        'is_published',
        'is_featured',
        'is_deleted',
    ],
];
نکته

نام فیلدها به‌صورت خودکار به حروف کوچک تبدیل می‌شوند. نیازی به اعمال strtolower نیست.

نحوه تولید نام ماکرو​

نام ماکرو از روی نام فیلد با استفاده از ()Str::studly ساخته می‌شود:

فیلدStudlyCaseماکروی onlyماکروی except
is_activeIsActive()onlyIsActive()exceptIsActive
is_publishedIsPublished()onlyIsPublished()exceptIsPublished
my_custom_flagMyCustomFlag()onlyMyCustomFlag()exceptMyCustomFlag

مدیریت خطا​

نوع اول — مقدار کانفیگ آرایه نیست​

// dornica-app.php
'additional_boolean_scope_fields' => 'is_published', // اشتباه: رشته است نه آرایه

// پرتاب می‌شود:
// "Given 'additional_boolean_scope_fields' key in [dornica-app.php] config file must be an array"

نوع دوم — عناصر آرایه رشته نیستند​

// dornica-app.php
'additional_boolean_scope_fields' => [true, 123], // اشتباه: نه رشته

// پرتاب می‌شود:
// "Given 'additional_boolean_scope_fields' key in [dornica-app.php] config file must be array of strings"

نکات مهم

  1. فیلدها باید به فرمت snake_case و حروف کوچک تعریف شوند.
  2. ماکروها روی تمام مدل‌هایی که از Eloquent Builder استفاده می‌کنند در دسترس هستند.
  3. فیلدهای تکراری میان لیست پیش‌فرض و کانفیگ به‌طور خودکار حذف می‌شوند.
  4. اعتبارسنجی کانفیگ قبل از ثبت هر ماکرویی اجرا می‌شود.

مثال کامل

// config/dornica-app.php
return [
    'additional_boolean_scope_fields' => [
        'is_published',
        'is_featured',
    ],
];
// استفاده در کد
User::onlyIsActive()
    ->exceptIsExpired()
    ->onlyIsVerified()
    ->paginate(20);

Product::onlyIsPublished()
    ->onlyIsActive()
    ->onlyIsFeatured()
    ->get();