بیلدرهای روان اعتبارسنجی لاراول | Fluent Rule Builders

بسیاری از قوانین اعتبارسنجی (Validation Rules) در لاراول به شکل رشته‌های متنی نوشته می‌شوند که پارامترهای آن‌ها پس از دو نقطه (:) قرار گرفته و با کاما از یکدیگر جدا می‌شوند. به عنوان مثال، قاعده‌ای مانند required_without:email به درستی عمل می‌کند، اما ادیتور یا IDE شما توانایی تکمیل خودکار (Autocomplete) آن را ندارد و اگر نام قانون را اشتباه تایپ کنید، این خطا فقط در زمان اجرای اعتبارسنجی مشخص خواهد شد.

کلاس Rule از پیش دارای متدهای سازنده برای قوانینی نظیر in، unique، exists، enum، date، email و file بود. اکنون نسخه 13.36 لاراول برای تمام قوانینی که تا پیش از این تنها به صورت رشته متنی قابل استفاده بودند، یک بیلدر اختصاصی ارائه کرده است.

قبل و بعد از تغییرات

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

$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\Validation\Rule;

$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 است. فهرست کامل این قوانین عبارت است از:

accepted()
activeUrl()
bail()
base64()
boolean()
declined()
exclude()
filled()
hexColor()
json()
list()
macAddress()
missing()
nullable()
present()
prohibited()
required()
sometimes()
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');

Rule::requiredArrayKeys('street', 'city', 'postcode');

فهرست کامل این قوانین شامل موارد زیر است:

acceptedIf()
declinedIf()
excludeWith()
excludeWithout()
inArray()
inArrayKeys()
missingIf()
missingUnless()
missingWith()
missingWithAll()
notRegex()
presentIf()
presentUnless()
presentWith()
presentWithAll()
prohibitedIfAccepted()
prohibitedIfDeclined()
prohibits()
regex()
requiredArrayKeys()
requiredIfAccepted()
requiredIfDeclined()
requiredWith()
requiredWithAll()
requiredWithout()
requiredWithoutAll()
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

Rule::currentPassword()->guard('admin'); // current_password:admin

متد version() روی Rule::ip() تنها مقادیر 4 یا 6 را قبول کرده و برای هر مقدار دیگر خطای InvalidArgumentException پرتاب می‌کند. این در حالی است که متد version() روی Rule::uuid() رشته‌های 'nil' و 'max' را نیز می‌پذیرد.

همچنین بیلدر تاریخ در همین نسخه مجهز به متد equals() شده است که قاعده date_equals را پیاده‌سازی می‌کند:

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

Rule::date()->equals(today());

مدیریت مقادیر حاوی کاما

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

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

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

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

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

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

مقادیر غیر رشته‌ای نیز به همان معادل رشته‌ای تبدیل می‌شوند؛ برای مثال true، false و null به ترتیب تبدیل به 'true'، 'false' و 'null' خواهند شد:

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

اگر یکی از این بیلدرها را برای مواردی مانند لاگ گرفتن به رشته Cast کنید، فرمت متنی حاصل برای هر مقداری که حاوی کاما یا دابل‌کوتیشن است، به صورت خودکار علامت کوتیشن قرار می‌دهد.

نمونه عملی در کلاس Form Request

در یک فرم نهایی تسویه حساب (Checkout)، می‌توان بیلدرهای پیشین را با امکانات جدید ترکیب کرد:

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

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

دیدگاه خود را درباره این تحلیل با دیگر خوانندگان به اشتراک بگذارید.

0 دیدگاه

ارسال دیدگاه جدید

نام یا نام‌مستعار *

آدرس ایمیل * (منتشر نمی‌شود)

متن دیدگاه یا تحلیل شما *

حاصل جمع یا تفریق تصویر را محاسبه و بنویسید

هنوز دیدگاهی برای این مقاله ثبت نشده است.

نخستین نفری باشید که دیدگاه یا نقد خود را درباره این موضوع می‌نویسد.