سازنده‌های قانون روان (Fluent Rule Builders) برای تمام قوانین اعتبارسنجی لاراول

بسیاری از قوانین اعتبارسنجی لاراول به صورت رشته نوشته می‌شوند که در آن‌ها پارامترها پس از یک دونقطه (colon) و با جداکننده کاما قرار می‌گیرند. قانونی مانند required_without:email کار می‌کند، اما ویرایشگر شما نمی‌تواند آن را تکمیل خودکار (autocomplete) کند و در صورت غلط املایی در نام قانون، خطا تنها زمانی رخ می‌دهد که اعتبارسنج اجرا شود.

کلاس Rule پیش از این دارای سازنده‌هایی برای قوانینی مانند in، unique، exists، enum، date، email و file بود. لاراول ۱۳.۳۶ برای هر قانونی که همچنان فقط به صورت رشته‌ای بود، یک سازنده اضافه کرده است.

قبل و بعد

در اینجا یک فرم پروفایل را مشاهده می‌کنید که با قوانین رشته‌ای اعتبارسنجی شده است:

$request->validate([
    'email' => 'required_without:phone|email',
    'phone' => 'required_without:email',
    'website' => 'nullable|url:https',
    'device_id' => 'uuid:4',
    'tags.*' => 'distinct:ignore_case',
    'password' => 'required|confirmed',
    'timezone' => 'timezone:per_country,US',

همان قوانین با استفاده از سازنده‌های جدید:

use Illuminate
ules
ule;

$request->validate([
    'email' => [Rule::requiredWithout('phone'), 'email'],
    'phone' => [Rule::requiredWithout('email')],
    'website' => [Rule::nullable(), Rule::url()->protocols(['https'])],
    'device_id' => [Rule::uuid()->version(4)],
    'tags.*' => [Rule::distinct()->ignoreCase()],
    'password' => [Rule::required(), Rule::confirmed()],
    'timezone' => [Rule::timezone(['per_country', 'US'])],

قوانین رشته‌ای همچنان کار می‌کنند و شما می‌توانید هر دو سبک را در یک آرایه با هم ترکیب کنید.

قوانین بدون پارامتر

این موارد قانون را به عنوان یک رشته ساده برمی‌گردانند، بنابراین Rule::required() همان رشته required است. لیست کامل این موارد شامل موارد زیر است:

1. accepted()
2. activeUrl()
3. bail()
4. base64()
5. boolean()
6. declined()
7. exclude()
8. filled()
9. hexColor()
10. json()
11. list()
12. macAddress()
13. missing()
14. nullable()
15. present()
16. prohibited()
17. required()
18. sometimes()
19. ulid()

ارسال مقدار true به Rule::boolean() مقدار boolean:strict را برمی‌گرداند که فقط مقادیر true و false را می‌پذیرد.

قوانینی که فیلدها یا مقادیر را می‌پذیرند

این قوانین، نام فیلدهای دیگر، کلیدها یا مقادیر را به عنوان آرگومان، چه به صورت آرایه و چه به صورت آرگومان‌های جداگانه، دریافت می‌کنند:

Rule::requiredWith('first_name', 'last_name');
Rule::requiredWith(['first_name', 'last_name']);

Rule::acceptedIf('plan', 'pro');
Rule::prohibits('coupon_code');

در اینجا مجموعه کامل این قوانین آمده است:

1. acceptedIf()
2. declinedIf()
3. excludeWith()
4. excludeWithout()
5. inArray()
6. inArrayKeys()
7. missingIf()
8. missingUnless()
9. missingWith()
10. missingWithAll()
11. notRegex()
12. regex()
13. presentIf()
14. presentUnless()
15. presentWith()
16. presentWithAll()
17. prohibitedIfAccepted()
18. prohibitedIfDeclined()
19. prohibits()
20. regex()
21. requiredArrayKeys()
22. requiredIfAccepted()
23. requiredIfDeclined()
24. requiredWith()
25. requiredWithAll()
26. requiredWithout()
27. requiredWithoutAll()
28. timezone()

قوانین دارای گزینه‌ها

این موارد یک شیء با متدهایی برای گزینه‌های قانون برمی‌گردانند:

Rule::url()->protocols(['https']);            // url:https
Rule::uuid()->version(7);                     // uuid:7
Rule::ip()->version(6);                       // ipv6
Rule::distinct()->strict()->ignoreCase();     // distinct:strict,ignore_case
Rule::confirmed()->customField('repeat_pass'); // confirmed:repeat_pass

متد version() در Rule::ip() مقادیر 4 یا 6 را می‌پذیرد و برای هر عدد دیگری یک InvalidArgumentException پرتاب می‌کند. در Rule::uuid()، متد version() همچنین رشته‌های 'nil' و 'max' را می‌پذیرد.

سازنده روان تاریخ (date builder) در همین نسخه یک متد equals() دریافت می‌کند که قانون date_equals را اضافه می‌کند:

Rule::date()->equals('2026-12-31');

مقادیر دارای کاما

فرمت رشته‌ای، پارامترها را بر اساس کاما جدا می‌کند. فرض کنید یک قانون accepted_if باید زمانی اعمال شود که فیلد plan برابر با Team, Annual باشد:

'terms' => 'accepted_if:plan,Team, Annual',

اعتبارسنج این را به عنوان دو مقدار Team و Annual می‌خواند و قانون هرگز با Team, Annual مطابقت پیدا نمی‌کند.

سازنده‌هایی که فیلدها یا مقادیر را می‌پذیرند، یک قرارداد (contract) جدید به نام ParameterizedRule را پیاده‌سازی می‌کنند. متد toArray() آن، نام قانون و پارامترهایش را به عنوان یک آرایه برمی‌گرداند و اعتبارسنج به جای تجزیه یک رشته، مستقیماً از آن آرایه استفاده می‌کند. مقدار، کامای خود را حفظ می‌کند:

'terms' => [Rule::acceptedIf('plan', 'Team, Annual')],

این موضوع همچنین شامل کوتیشن‌ها، پایپ‌ها (pipes) و بک‌اسلش‌ها در مقادیر، و نام فیلدها یا کلیدهایی که حاوی کاما هستند (مانند کلید آرایه برای Rule::requiredArrayKeys()) می‌شود.

مقادیر غیررشته‌ای به رشته‌هایی تبدیل می‌شوند که فرمت رشته‌ای از آن‌ها استفاده می‌کند، بنابراین true، false و null به 'true'، 'false' و 'null' تبدیل می‌شوند:

Rule::presentIf('is_company', true); // present_if:is_company,true

اگر یک سازنده را به رشته تبدیل کنید (مثلاً برای لاگ کردن)، فرمت رشته‌ای را با کوتیشن در اطراف هر مقداری که حاوی کاما یا دابل کوتیشن باشد، دریافت خواهید کرد.

یک مثال از Form Request

یک Form Request برای تسویه حساب ممکن است سازنده‌های موجود را با موارد جدید ترکیب کند:

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class CheckoutRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'plan' => [Rule::required(), Rule::in(['starter', 'Team, Annual'])],
            'terms' => [Rule::acceptedIf('plan', 'Team, Annual')],
            'company_name' => [Rule::requiredIfAccepted('is_business')],
            'vat_number' => [Rule::nullable(), Rule::requiredWith('company_name')],
            'billing' => [Rule::required(), Rule::requiredArrayKeys('street', 'city', 'postcode')],
            'coupon_code' => [Rule::nullable(), Rule::prohibits('gift_card')],
            'website' => [Rule::nullable(), Rule::url()->protocols(['https'])],
            'emails.*' => [Rule::distinct()->ignoreCase(), 'email'],
        ];
    }

منبع و مطالعه گزارش کامل به زبان اصلی: Laravel News