آشنایی با انواع قوانین اعتبارسنجی (Validation) در لاراول

همانطور که فصل ۱۳-۱ مشاهده کردید به توضیح دقیق اعتبارسنجی پرداختیم. اما نکته‌ای که حائز اهمیت بود و در فصل ۱۳-۱ به آن اشاره نکردیم، انواع قوانین اعتبارسنجی است، این قوانین به عنوان روش‌هایی برای کنترل اطلاعات ارسالی کاربران که از قبل روی فیلدها اعمال شده، بکارگرفته می‌شوند. برای آشنایی بیشتر با این قوانین یا rules با ما همراه باشید:

توجه دارید که این قوانین همواره به صورت زیر به کنترلر یا اعتبارسنج ما اعمال خواهند شد:

'fieldName' => 'rule1|rule2|rule3'

accepted

فیلدی که زیرنظر این قانون کنترل می‌شود باید مقادیر yes, on, 1‌ یا true را بپذیرد تا مورد تایید باشد. از این اعتبارسنجی معمولا برای بخش «تایید قوانین و سیاست‌های سایت» استفاده می‌شود.

after:date

فیلدی که زیر نظر این قانون کنترل می‌شود باید مقداری را به عنوان تاریخ ارسال کند که بعد از تاریخ موجود در date باشد. توجه داشته باشید که با اعمال این قانون، date به تابع پی اچ پی strtotime ارسال می‌شود. به نمونه‌ی زیر توجه کنید:

'start_date' => 'required|date|after:tomorrow'

بجای ارسال رشته‌ای date برای strtotime می‌تواون یک فیلد دیگر را برای مقایسه ارسال کرد. مثلا در مثال زیر بررسی می‌شود که آیا تاریخ فیلد start_date از تاریخ فیلد finish_date عقب‌تر است یا نه؟ درصورتیکه بزرگتر نباشد خطا ارسال خواهد خواهد شد:

'finish_date' => 'required|date|after:start_date'

after_or_equal:date

از این قانون دقیقا مشابه قانون فوق است با این تفاوت که مقادیر مساوی را برای تاریخ می‌پذیرد.

alpha

فیلدی که زیر نظر این قانون کنترل می‌شود باید شامل کاراکترهای حروف الفبا باشد.

alpha_dash

فیلدی که زیر نظر این قانون کنترل می‌شود باید کاراکترهای شامل حروف و عدد، علامت (-) و یا آندرلاین (ـ) باشند.

alpha_num

فیلدی که زیر نظر این قانون کنترل می‌شود باید شامل کاراکترهای حروفی-عددی باشد.

array

فیلدی که از این قانون استفاده می‌کند باید یک آرایه‌ی PHP باشد.

before:date

دقیقا مشابه قانون after است با این تفاوت که تاریخ ارسالی باید کوچکتر از تاریخ date باشد.

before_or_equal:date

این قانون دقیقا مشابه after_or_equal است با این تفاوت که تاریخ ارسالی باید کوچکتر یا مساوی date باشد.

between:min, max

فیلدی که زیر نظر این قانون کنترل می‌شود باید سایزی بین mix و max داشته باشد. رشته‌ها، اعداد و فایل‌ها بر اساس قانون size که در ادامه توضیح داده خواهد شد بررسی می‌شوند.

boolean

فیلدی که زیر نظر این قانون کنترل می‌شود باید به عنوان یک مقدار بولین باشد. ورودی‌هایی که می‌پذیرد برابر است با:‌ true, false, 0, 1 و همچنین "1" و "0".

confrimed

از این قانون برای مچ کردن اطلاعات استفاده می‌شود. مثلا اگر یک فیلد به نام password داشته باشیم اگر قانون confirmed روی فیلد password اعمال شود، یک فیلد دیگر به نام password_confirmation باید در فرم وجود داشته باشد تا تطابق بررسی شود.

date

فیلدی که زیر نظر این قانون کنترل می‌شود باید یک تاریخ صحیح (یک تاریخ با فرمت نگارشی مطابق با تابع strtotime) ارائه دهد.

date_format:format

فیلدی که زیر نظر این قانون کنترل می‌شود باید از format برای درج تاریخ استفاده کند. درنظر داشته باشید که باید از date یا date_format برای اعتبارسنجی تاریخ استفاده کنید و نمی‌توانید هر دو آنها را به صورت همزمان اعمال کنید.

different:field

با بکارگیری این قانون، باید فیلد موردنظر مقداری متفاوت از field داشته باشد (برای همواره متفاوت بودن دو فیلد استفاده می‌شود).

digits:value

با بکارگیری این قانون، فیلد موردنظر باید همواره عددی و طول آن دقیقا برابر value باشد.

digits_between:min,max

با بکارگیری این قانون، فیلد موردنظر باید همواره مقداری بین mix و max داشته و از نوع عددی باشد.

dimensions

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

'avatar' => 'dimensions:min_width=100,min_height=200'

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

min_width, max_width, min_height, max_height, width, height, ratio

قید ratio به عنوان یک نسبت معادل تقسیم عرض به طول می‌باشد. که برای نمایش آن می‌توان از 3/2 یا 1.5 استفاده کرد:

'avatar' => 'dimensions:ratio=3/2'

نکته‌ی بسیار مهم: این قانون به چندین آرگومان نیاز دارد. همچنین ممکن است از متد Rule:dimensions برای اعمال مستقیم محدودیت‌ها استفاده کرد:

use Illuminate\Validation\Rule;

Validator::make($data, [
    'avatar' => [
        'required',
        Rule::dimensions()->maxWidth(1000)->maxHeight(500)->ratio(3 / 2),
    ],
]);

distinc

این قانون برای حالتی که با آرایه‌ها کار می‌کنیم بسیار مفید است. فیلدهایی که از این قانون تبعیت می‌کنند همواره نباید هیچگونه مقدار مشابه‌ای داشته باشند:

'foo.*.id' => 'distinct'

email

با بکارگیری این قانون، فیلد موردنظر باید به صورت آدرس ایمیل باشد.

exists:table,column

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

یک مثال کاربردی:

'state' => 'exists:states'

در قانون بالا بررسی می‌کنیم که آیا جدول موردنظر وجود دارد یا خیر؟

همچنین با استفاده از دستور زیر بررسی می‌‎کنیم که آیا جدول موردنظر به همراه نام ستون موردنظر وجود دارد یا خیر؟

'state' => 'exists:states,abbreviation'

گاهی نیاز داریم که یک دیتابیس خاص را بر اساس اتصالات پایگاه داده مشخص کنیم برای اینکار از نام جدول به همراه اسم کانکشن با استفاده از علامت . استفاده می‌کنیم:

'email' => 'exists:connection.staff,email'

همچنین می‌توان از کوئری‌ها برای شخصی‌سازی استفاده کرد. ممکن است شما از کلاس Rule استفاده کنید:

use Illuminate\Validation\Rule;

Validator::make($data, [
    'email' => [
        'required',
        Rule::exists('staff')->where(function ($query) {
            $query->where('account_id', 1);
        }),
    ],
]);

file

فیلدی که زیر نظر این قانون کنترل می‌شود باید همواره یک فایل با آپلود موفقیت آمیز باشد.

filled

فیلدی که با این قانون کنترل می‌شود همواره باید مقدار داشته باشد.

image

فیلدی که از این قانون تبعیت می‌کند باید عکس با فرمت jpeg, png, bmp, gif‌ و svg باشد.

in:foo,bar,...

فیلدی که زیر نظر این قانون کنترل می‌شود باید همواره شامل لیستی از مقادیر انتخابی باشد. از این قانون اغلب به صورت مستقیم بهره می‌بریم. توجه داریم که در صورت زیاد بودن مقادیر که با کاما , از هم جدا شده اند باید همواره از تابع implode استفاده کرد:

'field' => 'required|in:' . implode(',', $this->allslots),

به مثال زیر توجه کنید:

use Illuminate\Validation\Rule;

Validator::make($data, [
    'zones' => [
        'required',
        Rule::in(['first-zone', 'second-zone']),
    ],
]);

in_array:anotherfield

فیلدی که از این قانون پیروی می‌کند همواره باید در مقادیر anotherfield موجود در یک آرایه، وجود داشته باشد. مثلا شما فرض کنید یک آرایه دارید که درون آن ۲۰ رشته است و می‌خواهید ورودی یک فیلد بگونه‌ای باشد که درون یکی از این ۲۰ مقدار همواره وجود داشته باشد.

integer

فیلدی که از این قانون پیروی می‌کند همواره باید یک مقدار صحیح باشد.

ip

فیلدی که از این قانون پیروی می‌کند همواره باید یک IP address باشد.

ipv4

فیلدی که از این قانون پیروی می‌کند همواره باید یک IPv4 address باشد.

ipv6

فیلدی که از این قانون پیروی می‌کند همواره باید یک IPv6 address باشد.

json

فیلدی که از این قانون پیروی می‌کند همواره باید یک رشته‌ی json مورد تایید باشد.

max:value

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

mimetypes:text/plain,...

فایلی که تحت این قانون کنترل شود باید MIME Type آن برابر مقدار روبه‌روی این قانون باشد:

'video' => 'mimetypes:video/avi,video/mpeg,video/quicktime'

mimes:foo,bar,...

فایلی که تحت این قانون کنترل می‌شود باید MIME type آن مطابق با یکی از پسوندهایی که در روبه‌روی آن نوشته می‌شود، باشد.

یک مثال ساده و کاربری:

'photo' => 'mimes:jpeg,bmp,png'

برای دستیابی به لیست کاملی از MIME Type ها می‌توانید روی این لینک کلیک کنید.

min:value

فیلدی که از این قانون پیروی می‌کند باید همواره کمتر از مقدار value نباشد.

nullabe

فیلدی که از این قانون پیروی می‌کند می‌تواند null باشد.

not_in:foo,bar,...

دقیقا عکس in:foo,bar, عمل می‌کند. با این قانون فیلد نباید شامل مقادیر موجود در لیست باشد.

numeric

با استفاده از این قانون باید فیلد موردنظر همواره عددی باشد.

present

فیلدی که این قانون را می‌پذیرد باید همواره داده‌ی ورودی را داشته باشد اما اگر خالی باشد هم مشکلی پیش نمی‌آید!

regex:pattern

فیلدی که از این قانون پیروی می‌کند همواره باید مقدار آن برابر Regular Expression یا عبارات با قاعده مشخص باشد.

required

فیلدی که از این قانون تبعیت کند باید همواره داده داشته باشد و نمی‌تواند خالی باشد. توجه داشته باشید که یک فیلد در صورتیکه هر یک از موارد زیر را شامل شود به عنوان یکی فیلد خالی شناخته خواهد شد:

مقدار null داشته باشد
مقدار آن رشته خالی باشد
مقدار آن یک آرایه خالی یا شیء countable خالی باشد
مقدار آن یک فایل بدون مسیر مشخص باشد

required_if:anotherfield,value,...

فیلدی که از این قانون پیروی می‌کند همواره باید خالی نباشد درصورتیکه فیلد anotherfield دارای مقدار value باشد. یعنی به صورت یک شرط عمل می‌کند. به مثال زیر توجه کنید. در این مثال دو select لیست داریم که دارای مقادیری هستند. یکی به عنوان مجموعه و دیگری تحت عنوان زیرمجموعه شناخته می‌شود:

<select id="category" name="category">
            <option value="a">Option A</option>
            <option value="b">Option B</option>
            <option value="c">Option C</option>
            <option value="d">Option D</option>
            <option value="e">Option E</option>
            <option value="f">Option F</option>
    </select>

    <select id="subcategory" name="subcategory">
            <option value="a">Suboption A </option>
            <option value="b">Suboption B </option>
            <option value="c">Suboption C </option>
            <option value="d">Suboption D </option>
            <option value="e">Suboption E </option>
    </select>

حال می‌خواهیم از شرط required_if استفاده کرده و بگوییم پر کردن یا انتخاب کردن فیلد subcategory تنها در صورتیکه یکی از مقادیر فیلد category انتخاب شود امکان پذیر است. به عبارت دیگر اگر فیلد موردنظر دارای مقدار مشخصی باشد همواره فیلد subcategory به صورت required خواهد بود.

required_unless:anotherfield,value,...

این قانون دقیقا عکس قانون required_if کار می‌کند. بدین صورت که اگر یک فیلد (anotherfield) دارای یک مقدار مشخص (value) باشد آنگاه آن فیلد می‌تواند خالی باشد. در واقع تفاوت بین if و unless در این است که اگر شرط صدق کند دستور های داخل if اجرا شده و اگر شرط صدق نکند دستورهای درون unless اجرا خواهند شد.

required_with:foo,bar,...

فیلدی که از این قانون پیروی می‌کند همواره required خواهد بود اگر فقط و فقط مقادیر مشخصی برای آن در نظر گرفته شود که این مقادیر می‌تواند به صورت foo, bar و ... باشد.

required_without:foo,bar,...

فیلدی که از این قانون پیروی می‌کند همواره به صورت required خواهد بود اگر و فقط اگر هر یک از مقادیر انتخابی برابر مقادیر مشخص نباشد. در اینجا مقادیر فرضی foo, bar... در نظر گرفته شده‌اند (حالت OR دارد).

required_without_all:foo,bar,...

فیلدی که از این قانون پیروی می‌کند همواره required خواهد بود اگر و فقط اگر همه‌ی مقادیر مشخص شده وجود نداشته باشند (حالت AND دارد).

same:field

هنگامیکه از این قانون استفاده شود، همواره field انتخاب شده باید با قوانین موجود در فیلدی که این قانون روی آن وضع شده است برابر باشد.

size:value

فیلدی که از این قانون پیروی می‌کند باید همواره سایز آن برابر value باشد. برای داده‌های رشته‌ای این value نمایانگر تعداد کاراکترهاست. برای داده‌های عددی این مقدار نمایانگر یک مقدار عدد صحیح است. برای آرایه‌ها این مقدار بیانگر count هر آرایه است (تعداد آرایه‌های موجود در آن). برای فایل‌‌ها این مقدار برابر سایز فایل بر حسب KB یا کیلوبایت است.

string

فیلدی که از این قانون پیروی می‌کند باید همواره از نوع استرینگ یا رشته باشد. در صورتیکه بخواهید این فیلد مقدار null‌ نیز بپذیرد همواره باید شما قانون nullable را روی آن نیز اعمال کنید.

timezone

فیلدی که از این قانون پیروی می‌کند باید همواره یک timezone‌ دقیق باشد. این timezone دقیق بر اساس تابع timezone_identifiers_list تنظیم شده است.

unique:table,column,except,idColumn

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

به عنوان مثال می‌خواهیم برای یک ستون خاص (در این مثال نام ستون email_address است) مقدار unique همواره ثبت کنیم:

'email' => 'unique:users,email_address'

گاهی ممکن است بخواهیم کل دیتابیس را تغییر داده و برای یک دیتابیس خاص و جدول موردنظر و در نهایت ستونی انتخابی دستور unique را اعمال کنیم:

'email' => 'unique:connection.users,email_address'

حال فرض کنید یک فرم برای بروزرسانی پروفایل کاربران در اختیار دارید. درون این فرم فیلدهای نام و نام خانوادگی، آدرس ایمیل و شماره تماس وجود دارد. از قبل فیلد ایمیل را به صورت Unique در دیتابیس تعریف کرده‌ایم. حال اگر بخواهیم درون این فرم مثلا نام و نام خانوادگی کاربر را ادیت کرده و دکمه‌ی ذخیره را بفشاریم، با خطای:‌ این ایمیل قبلا ثبت شده است مواجهه خواهیم شد. حال برای برطرف کردن این خطا باید ID این رکورد را برای فیلد email درآورده و خاصیت یکتایی را از آن برداریم. با انجام اینکار در صورت بروزرسانی هر یک از فیلدها یکتایی email بررسی نخواهد شد. بنابراین داریم:

Validator::make($data, [
    'email' => [
        'required',
        Rule::unique('users')->ignore($user->id),
    ],
]);

همانطور که ملاحظه می‌کنید در مثال بالا به جای علامت | از آرایه به همراه علامت , استفاده کرده‌ایم. همچنین اگر جدول شما فیلد خارجی داشت باید آن را به متد ignore اضافه کنید:

'email' => Rule::unique('users')->ignore($user->id, 'user_id')

علاوه بر این می‌توان از قیود کوئری‌ها برای شخصی‌سازی استفاده کرد:

'email' => Rule::unique('users')->where(function ($query) {
    $query->where('account_id', 1);
})

url

فیلدی که از این قانون پیروی می‌کند همواره باید یک url و آدرس اینترنتی معتبر باشد.

با مطالعه‌ی مباحث فوق به تمام قوانین پایه‌ی اعتبارسنجی در لاراول تسلط پیدا کردید. با بررسی دقیق این قوانین متوجه خواهید شد که چگونه می‌توان فرم‌های هوشمند و حرفه‌ای ایجاد کرد. در فصل ۱۳-۳ به بررسی نحوه‌ی ایجاد شروط و قوانین پیشرفته‌تر اشاره خواهیم کرد تا مبحث Validation‌ را به صورت کامل به اتمام برسانیم.

فصل ۱۳-۲:‌ آشنایی با انواع قوانین اعتبارسنجی (Validation) در لاراول