آموزش Validation در Laravel

سنجش اعتبار / Validation در Laravel

1. مقدمه
2. شروع کار با سنجش اعتبار / validation
   • تعریف Route ها
   • ایجاد controller
   • نوشتن منطق اعتبارسنجی / validation
   • نمایش خطاهای اعتبارسنجی
   • درخواست های AJAX و اعتبارسنجی
   • اعتبارسنجی آرایه ها
3. دیگر روش ها و رویکردهای اعتبارسنجی
   • ایجاد validator به صورت دستی
   • اعتبارسنجی form request
4. کار با پیغام های خطا
   • پیغام های خطای اختصاصی و سفارشی شده
5. قوانین و معیار های موجود اعتبارسنجی
6. اضافه کردن معیارها و قوانین اعتبارسنجی متناسب با شرایط
7. معیارها و قوانین اعتبارسنجی سفارشی شده

مقدمه

Laravel رویکردهای متعددی در رابطه با اعتبارسنجی داده های ورودی اپلیکیشن ارائه می کند. به صورت پیش فرض، کلاس controller پایه چارچوب نرم افزاری Laravel از یک مشخصه (trait) به نام ValidatesRequests بهره می گیرد. این trait با فراهم نمودن معیارها و قوانین اعتبارسنجی بهینه متدی کارآمد و آسان برای سنجش اعتبار درخواست HTTP ورودی ارائه می کند.

شروع کار با سنجش اعتبار / validation

جهت آشنایی با امکانات قدرتمند درست سنجی لاراول نگاهی به یک نمونه ی کامل از اعتبارسنجی فرم و نمایش پیغام های خطا به کاربر می اندازیم.

تعریف Route ها

در گام نخست فرض بگیرید route های زیر را در فایل app/Http/routes.php تعریف شده داریم:

// Display a form to create a blog post...
Route::get('post/create', 'PostController@create');
// Store a new blog post...
Route::post('post', 'PostController@store');

متد Route::get یک فرم جهت ایجاد پست جدید در وبلاگ برای کاربر به نمایش می گذارد. متد post نیز پست جدید وبلاگ را در پایگاه داده ذخیره می کند.

ایجاد Controller

در گام بعدی توجه خود را به یک controller ساده که این route ها را مدیریت می کند، جلب می کنیم. متد store را هم اکنون تهی می گذاریم:

<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class PostController extends Controller
{
   /**
    * Show the form to create a new blog post.
    *
    * @return Response
    */
   public function create()
   {
       return view('post.create');
   }
   /**
    * Store a new blog post.
    *
    * @param Request $request
    * @return Response
    */
   public function store(Request $request)
   {
       // Validate and store the blog post...
   }
}

نوشتن منطق اعتبارسنجی

اکنون متد store در مثال بالا را با منطق درست سنجی پست ایجاد شده در وبلاگ پر می کنیم. اگر کلاس controller پایه ی اپلیکیشن خود (App\Http\Controllers\Controller) را بررسی کنید، می بینید که کلاس مورد نظر از یک trait به نام ValidatesRequests استفاده می کند. این trait یک متد کارآمد به نام validate در تمامی کلاس های controller شما لحاظ می کند.
متد validate یک درخواست HTTP ورودی و یک سری معیار اعتبارسنجی (validation rules) به عنوان آرگومان ورودی می پذیرد. در صورت منطبق بودن معیارهای اعتبارسنجی (با موفقیت انجام شدن اعتبارسنجی)، کد مورد نظر با روال عادی همواره اجرا می شود. اما اگر اعتبارسنجی با شکست مواجه شد، یک خطا صادر شده و متعاقبا پاسخ خطای مناسب به صورت خودکار به کاربر برگردانده می شود. در سناریو درخواست های HTTP متعارف ، یک redirect response ایجاد می شود (کاربر به صفحه ی قبلی بازگردانده می شود) اما برای درخواست های از نوع AJAX پاسخ با فرمت JSONبه مرورگر بازگردانده می شود.
برای درک بهتر متد validate، بار دیگر به متد store برمی گردیم:

/**
 * Store a new blog post.
 *
 * @param Request $request
 * @return Response
 */
public function store(Request $request)
{
   $this->validate($request, [
       'title' => 'required|unique:posts|max:255',
       'body' => 'required',
   ]);
   // The blog post is valid, store in database...
}

همان طور که می بینید، درخواست HTTP ورودی و قوانین اعتبارسنجی دلخواه را به متد validate ارسال می کنیم. اگر درست سنجی با شکست مواجه شد، پاسخ مناسب به طور خودکار تولید می شود. اما در صورتی که اعتبارسنجی با موفقیت انجام شد، controller با روال عادی به اجرا ادامه می دهد.

متوقف کردن اجرای قوانین اعتبارسنجی با اولین عدم موفقیت درست سنجی

برای اینکه با شکست در اولین تلاش برای اعتبارسنجی، اجرای قوانین اعتبارسنجی برای attribute معین را متوقف نمایید، کافی است معیار bail را بهattribute مورد نظر تخصیص دهید

$this->validate($request, [
   'title' => 'bail|required|unique:posts|max:255',
   'body' => 'required',
]);

در این مثال، اگر معیار required در خصوص اتریبیوت title با شکست مواجه شود، معیار unique (که از نظر مکانی دومین معیار اعمال شده است) دیگر مورد بررسی قرار نخواهد گرفت. با توجه به آنچه گفته شد نتیجه می گیریم که معیارها به همان ترتیب فیزیکی که تخصیص داده می شوند، اعتبارسنجی می گردند.

یک نکته در خصوص attribute های تودرتو

اگر درخواست HTTP شما دربردارنده ی پارامترهای تودرتو (nested) هست، می توانید آن ها را با استفاده از عملگر نقطه در معیارهای اعتبارسنجی خود مشخص نمایید:

$this->validate($request, [
   'title' => 'required|unique:posts|max:255',
   'author.name' => 'required',
   'author.description' => 'required',
]);

نمایش خطاهای اعتبارسنجی

حال با این سوال مواجه می شویم: اگر پارامترهای درخواست ورودی با قوانین اعتبارسنجی مورد نظر منطبق نباشد چی؟ همان طور که قبلا ذکر شد،Laravel به صورت خودکار کاربر را به مکان قبلی بازگشت می دهد. علاوه بر آن، تمامی خطاهای اعتبارسنجی به صورت اتوماتیک داخل session ذخیره (flash) می شوند.
همان طور که می بینید هیچ نیازی به bind کردن پیغام های خطا به صورت صریح به view مورد نظر در متد Route::get نبود. چرا که Laravel تمامی خطاها را در داده های session یافته و (در صورت وجود) آن ها را به صورت خودکار به view متصل (bind) می کند. متغیر $errors نمونه ای ازIlluminate\Support\MessageBag می باشد.

بنابراین در مثال حاضر اگر عملیات اعتبارسنجی ناموفق باشد، کاربر به متد create کنترلر بازگشت (redirect) داده می شود. این امر به ما اجازه می دهد پیغام های خطا را در view نمایش دهیم:

<!-- /resources/views/post/create.blade.php -->
<h1>Create Post</h1>
@if (count($errors) > 0)
                <div class="alert alert-danger">
                <ul>
           @foreach ($errors->all() as $error)
                <li>{{ $error }}</li>
           @endforeach
       </ul>
   </div>
@endif
<!-- Create Post Form -->

تنظیم سفارشی فرمت خطاهای ذخیره شده در session

اگر می خواهید (زمانی که عملیات درست سنجی با شکست مواجه شد) فرمت خطاهای اعتبارسنجی که در session ذخیره شده اند را به صورت اختصاصی تنظیم نمایید، می بایست formatValidationErrors را در کنترلر پایه بازنویسی (override) کنید. لازم است کلاسIlluminate\Contracts\Validation\Validator را نیز با استفاده از دستور use در بالای فایل وارد (import) کنید:

<?php
namespace App\Http\Controllers;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Contracts\Validation\Validator;
use Illuminate\Routing\Controller as BaseController;
use Illuminate\Foundation\Validation\ValidatesRequests;
abstract class Controller extends BaseController
{
   use DispatchesJobs, ValidatesRequests;
   /**
    * {@inheritdoc}
    */
   protected function formatValidationErrors(Validator $validator)
   {
       return $validator->errors()->all();
   }
}

درخواست های AJAX و Validation

در این مثال از یک فرم متعارف برای ارسال داده ها به اپلیکیشن استفاده می کنیم. بیشتر اپلیکیشن ها از درخواست های AJAX استفاده می کنند. اگر از متد validate در درخواست های AJAX خود استفاده کنید، Laravel هیچ پاسخ redirect ای ایجاد نمی کند. در عوض یک پاسخ به فرمتJSON حاوی تمامی خطاهای اعتبارسنجی تولید می کند و آن را همراه با کد وضعیت HTTP 422 به مرورگر برمی گرداند.

اعتبارسنجی آرایه ها

درست سنجی فیلد های ورودی فرم از نوع آرایه بسیار آسان می باشد. به عنوان مثال برای بررسی اینکه تمامی ایمیل های موجود در فیلد ورودی از نوع آرایه، یک آدرس ایمیل های منحصربفرد باشد، کافی است کد زیر را پیاده سازی کنید:

$validator = Validator::make($request->all(), [
   'person.*.email' => 'email|unique:users',
   'person.*.first_name' => 'required_with:person.*.last_name',
]);

زمانی که پیغام های اعتبارسنجی را در فایل های language خود مشخص می کنید، می توانید با افزودن یک کاراکتر * از آن پیغام برای تمامی فیلدهای ورودی آرایه ای خود استفاده کنید:

'custom' => [
   'person.*.email' => [
       'unique' => 'Each person must have a unique e-mail address',
   ]
],

دیگر روش ها و رویکردهای اعتبارسنجی

ایجاد validator به صورت دستی

می توان بجای استفاده از متد validate (مشتق شده از تریت ValidatesRequests)، با استفاده از Validator façade خود یک نمونه از کلاسvalidator به صورت دستی ایجاد نمایید. متد make که در facade نام برده فراخوانده می شود، نمونه ی لازم از validator را ایجاد می کند:

<?php
namespace App\Http\Controllers;
use Validator;
use Illuminate\Http\Request;
use App\Http\Controllers\Controller;
class PostController extends Controller
{
   /**
    * Store a new blog post.
    *
    * @param Request $request
    * @return Response
    */
   public function store(Request $request)
   {
       $validator = Validator::make($request->all(), [
           'title' => 'required|unique:posts|max:255',
           'body' => 'required',
       ]);
       if ($validator->fails()) {
           return redirect('post/create')
                       ->withErrors($validator)
                       ->withInput();
       }
       // Store the blog post...
   }
}

اولین آرگومان ارسالی به متد make، اطلاعاتی است که اعتبارسنجی می شود. دومین آرگومان معیارهای اعتبارسنجی است که بر روی داده ها اعمال می شود.
پس از بررسی و کسب اطمینان از نادرست بودن اطلاعات درخواست در سنجش اعتبار (پس از اینکه اعتبار و درستی درخواست با توجه به معیارهای اعتبارسنجی رد شد)، می توانید از متد withErrors برای ذخیره ی (flash) پیغام های خطا در session استفاده کنید. در صورت استفاده از این متد، متغیر $errors پس از redirection به صورت خودکار بین تمامی view به اشتراک گذاشته می شود. این امر به شما اجازه می دهد به راحتی خطاها را برای کاربر نمایش دهید. متد withErrors یک نمونه از کلاس validator، MessageBag یا آرایه ی PHP را به عنوان آرگومان می پذیرد.

نام گذاری error bag ها (بسته های نام گذاری شده خطا)

زمانی که چندین فرم در یک صفحه ی واحد قرار می گیرد، در این شرایط بد نیست برای MessageBag مربوط به خطاها نام تعیین کنید. بدین وسیله می توان پیغام های خطای مربوط به هر فرم را به راحتی بازیابی نمود. کافی است یک اسم را به عنوان آرگومان دوم به متد withErrors ارسال کنید:

return redirect('register')
           ->withErrors($validator, 'login');

سپس می توان به صورت زیر از طریق متغیر $errors به نمونه ی ایجاد شده از کلاس MessageBag دسترسی داشت:

                    {{ $errors->login->first('email') }}

متد after

validator به شما اجازه می دهد توابع callback ای را به عنوان آرگومان به کد پیوست کنید که پس از اتمام سنجش اعتبار و validation اجرا می شوند. این کار به شما اجازه می دهد به راحتی اعتبارسنجی بیشتری انجام داده و پیغام های خطای دیگری را به مجموعه پیغام ها اضافه کنید. برای شروع، متد after را در نمونه ی ایجاد شده از validator صدا می زنیم:

$validator = Validator::make(...);
$validator->after(function($validator) {
   if ($this->somethingElseIsInvalid()) {
       $validator->errors()->add('field', 'Something is wrong with this field!');
   }
});
if ($validator->fails()) {
   //
}

اعتبارسنجی درخواست های فرم (کلاس form request)

برای سناریوهای پیچیده تر سنجش اعتبار، می توانید یک form request ایجاد کنید. form request ها کلاس های سفارشی درخواست هستند که حاوی منطق سنجش اعتبار و validation می باشند. برای ایجاد یک کلاس form request، ابتدا دستور آرتیزان make:request را اجرا می کنیم:

                    php artisan make:request StoreBlogPostRequest

کلاس ایجاد شده داخل پوشه یapp/Http/Requests جایگذاری می شود. حال تعدادی قوانین و معیار اعتبارسنجی به متد rules اضافه می کنیم:

/**
 * Get the validation rules that apply to the request.
 *
 * @return array
 */
public function rules()
{
   return [
       'title' => 'required|unique:posts|max:255',
       'body' => 'required',
   ];
}

حال چگونه قوانین اعتبارسنجی را ارزیابی می کنیم؟ تنها کاری که باید انجام دهید type-hint (اعلان-نوع) request در متد controller می باشد. درخواست ورودی (incoming form request) پیش از اینکه متد controller فراخوانی شود، اعتبارسنجی می گردد. بنابراین دیگر نیازی نیست شما منطق validation را داخل controller تعریف کرده و کد خود را به هم ریخته کنید:

/**
 * Store the incoming blog post.
 *
 * @param StoreBlogPostRequest $request
 * @return Response
 */
public function store(StoreBlogPostRequest $request)
{
   // The incoming request is valid...
}

اگر اعتبار سنجی با موفقیت انجام نشد، یک پاسخ redirect تولید شده و کاربر را به صفحه ی قبلی بازگشت می دهد. همچنین تمامی خطاها داخلsession ذخیره شده و برای نمایش به کاربر در دسترس خواهند بود. اگر درخواست از نوع AJAX بود، یک پاسخ HTTP با کد وضعیت 422 به همراه یک فایل JSON حاوی خطاهای اعتبارسنجی (خطاها با فرمت JSON) به کاربر برگردانده می شد.

متد authorize

کلاس form request همچنین یک متد به نام authorize ارائه می کند. داخل این متد می توان بررسی کرد آیا کاربر احراز هویت شده واقعا مجوز بروز رسانی منابع مورد نظر را دارد یا خیر. به عنوان مثال، اگر کاربری سعی بر بروز رسانی دیدگاه مربوط به یک پست معین را داشته باشد، می توان بررسی کرد آیا این کاربر مالک دیدگاه مورد نظر است یا خیر.

/**
 * Determine if the user is authorized to make this request.
 *
 * @return bool
 */
public function authorize()
{
   $commentId = $this->route('comment');
 
   return Comment::where('id', $commentId)
                 ->where('user_id', Auth::id())->exists();
}

همان طور که در مثال می بینید متدی به نام route را صدا می زنیم. این متد امکان دسترسی به پارامترهای url تعریف شده در route مورد فراخوانی را می دهد، مانند پارامتر {comment} در نمونه ی زیر:

                    Route::post('comment/{comment}');

در صورتی که متد authorize مقدار بولی false را به عنوان خروجی برگرداند، یک پاسخ HTTP با کد وضعیت 403 به صورت خودکار به مروگر بازگردانده شده و در پی آن متد controller نیز اجرا نمی گردد.
چنانچه قصد دارید منطق مجوزدهی (authorization) را در بخش دیگری از اپلیکیشن خود قرار دهید، کافی است مقدار true را از متد authorizeبرگردانید:

/**
 * Determine if the user is authorized to make this request.
 *
 * @return bool
 */
public function authorize()
{
   return true;
}

تنظیم سفارشی فرمت خطای ذخیره شده در session

اگر می خواهید پس از رد اعتبار (شکست عملیات validation) فرمت خطاهای اعتبارسنجی که در session ذخیره شده اند را سفارشی تنظیم نمایید، کافی است formatErrors را در درخواست پایه (App\Http\Requests\Request) بازنویسی نمایید. یادآور می شویم که باید کلاسIlluminate\Contracts\Validation\Validator را با دستور use در بالای برنامه ی خود وارد (import) نمایید:

/**
 * {@inheritdoc}
 */
protected function formatErrors(Validator $validator)
{
   return $validator->errors()->all();
}

سفارشی سازی پیغام های خطا

جهت بازنویسی پیغام های خطایی که توسط form request مورد استفاده قرار می گیرد، می بایست متد messages را بازنویسی کنید. این متد در خروجی آرایه ای از جفت های attribute / rule را به همراه پیغام های خطای مربوطه ی آن ها برمی گرداند:

/**
 * Get the error messages for the defined validation rules.
 *
 * @return array
 */
public function messages()
{
   return [
       'title.required' => 'A title is required',
       'body.required' => 'A message is required',
   ];
}

کار با پیغام های خطا

پس از فراخوانی متد errors برای نمونه ی ایجاد شده از کلاس Validator، نمونه ای از Illuminate\Support\MessageBag را در خروجی دریافت می کنید. این نمونه مجموعه ای از توابع کارآمد ویژه ی کار با پیغام های خطا را در اختیار ما قرار می دهد.

بازیابی اولین پیغام خطای یک فیلد

به منظور بازیابی اولین پیغام خطای یک فیلد، متد first را صدا می زنیم:

$messages = $validator->errors();
echo $messages->first('email');

بازیابی تمامی پیغام های خطای یک فیلد

چنانچه می خواهید آرایه ای از تمامی پیغام های خطا را برای یک فیلد بدست آورید، کافی است متد get را صدا بزنید:

foreach ($messages->get('email') as $message) {
   //
}

بازیابی تمامی پیغام های خطا برای تمامی فیلدها

برای بازیابی آرایه ای از تمامی پیام های خطا مربوط به تمامی فیلدها، متد all را مورد استفاده قرار می دهیم:

foreach ($messages->all() as $message) {
   //
}

بررسی وجود یا عدم وجود پیغام برای یک فیلد

if ($messages->has('email')) {
   //
}

بازیابی پیغام خطا با فرمت خاص

                    echo $messages->first('email', '<p>:message</p>');

بازیابی تمامی پیغامهای خطا با فرمت معین

foreach ($messages->all('<li>:message</li>') as $message) {
   //
}

پیغام های خطای اختصاصی

در صورت لزوم می توان بجای پیام های پیش فرض، پیغام های خطای سفارشی پس از رد اعتبار برای نمایش به کاربر ایجاد کرد و مورد استفاده قرار داد. روش های مختلفی برای تعریف پیغام های سفارشی وجود دارد. اولین روش، ارسال پیغام های سفارشی به عنوان آرگومان سوم به متدValidator::make می باشد:

$messages = [
   'required' => 'The :attribute field is required.',
];
$validator = Validator::make($input, $rules, $messages);

در مثال حاضر، مکان نگهدار (place-holder) :attribute با اسم واقعی فیلد مورد اعتبارسنجی جایگزین می گردد. در صورت نیاز می توانید place-holder های دیگر مانند مثال زیر در پیام های اعتبارسنجی خود استفاده نمایید. مثال:

$messages = [
   'same'   => 'The :attribute and :other must match.',
   'size'   => 'The :attribute must be exactly :size.',
   'between' => 'The :attribute must be between :min - :max.',
   'in'     => 'The :attribute must be one of the following types: :values',
];

تعریف یک پیغام خطای سفارشی برای attribute مورد نظر

گاهی لازم می شود یک پیغام سفارشی خاص را تنها ویژه ی یک فیلد مشخص تعریف کرده و نمایش دهیم. برای این منظور کافی است از عملگر نقطه استفاده کنید. نحوه ی ویرایش آن: ابتدا اسم attribute و به دنبال آن معیار اعتبارسنجی (rule) را مشخص نمایید:

$messages = [
   'email.required' => 'We need to know your e-mail address!',
];

تعریف پیغام های سفارشی در فایل های Language

در بیشتر موارد توصیه می شود پیغام های سفارشی مربوط به attribute دلخواه را بجای اینکه مستقیم به validator ارسال کنید، داخل یک فایلlanguage تعریف نمایید. برای این منظور، پیغام های سفارشی را به آرایه ی custom در فایل resources/lang/xx/validation.php اضافه می کنیم:

'custom' => [
   'email' => [
       'required' => 'We need to know your e-mail address!',
   ],
],

معیارها و قوانین سنجش اعتبار موجود

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

accepted

فیلدی که اعتبارسنجی می شود بایستی دارای مقادیر yes، on، 1 یا true باشد. این قانون مناسب پذیرش اعتبارسنجی شرایط استفاده از سرویس و خدمات "Terms of Service" می باشد.

active_url

فیلدی که اعتبارسنجی می شود بایستی بر اساس تابع checkdnsrr زبان PHP یک URL معتبر و مجاز باشد.

after:date

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

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

بجای اینکه یک رشته حاوی مقدار تاریخ برای ارزیابی به تابع strtotime فرستاده شود، می توان فیلد دیگری برای مقایسه با تاریخ مورد نظر تعریف کنید:

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

alpha

فیلدی که اعتبارسنجی می شود می بایست کاملا از کاراکترهای حروف الفبا تشکیل شده باشد.

alpha_dash

فیلدی که اعتبارسنجی می شود می تواند کاراکترهای از نوع حروفی-عددی حاوی خط تیره و زیر خط باشد.

alpha_num

فیلدی که اعتبارسنجی می شود می بایست کاملا از کاراکترهای حروفی-عددی تشکیل شده باشد.

array

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

before:date

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

between:min,max

فیلد مورد اعتبارسنجی باید دارای مقداری با اندازه ی بین مقدار min و max تعریف شده باشد. مقادیر رشته ای، عددی و فایل ها به همان شیوه ی قانون سنجش اعتبار size ارزیابی و درست سنجی می شوند.

Boolean

فیلدی که اعتبار و درستی آن سنجیده می شود بایستی قابل تبدیل به مقدار بولی باشد (امکان تبدیل نوع آن به نوع داده ای بولی وجود داشته باشد). ورودی قابل قبول عبارتند از true، false، 1، 0 یا "1" و "0".

confirmed

فیلد مورد اعتبارسنجی بایستی یک فیلد منطبق و همخوان با foo_confirmation داشته باشد. برای مثال، اگر فیلدی که اعتبارسنجی می شودpassword باشد، لازم است یک فیلد متناظر password_confirmation در ورودی حاضر باشد.

date

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

date_format:format

فیلدی که اعتبار سنجی می شود باید با format مشخص شده منطبق باشد. فرمت ارائه شده بر اساس تابع date_parse_from_format زبانPHP ارزیابی و سنجیده می شود. به هنگام سنجش اعتبار یک فیلد باید یا data و یا date format را بکار ببرید (استفاده ی همزمان از این دو امکان پذیر نیست).

different:field

فیلد مورد سنجش اعتبار باید مقداری غیر از مقدار field ارائه شده داشته باشد.

digits:value

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

digits_between:min,max

فیلدی که اعتبارسنجی می شود باید دارای طولی مشخص بین دو مقدار min و max داشته باشد.

dimensions

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

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

محدودیت های موجود و قابل قبول عبارتند از: min_width، max_width، min_height، max_height، width، height و ratio.

distinct

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

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

email

فیلد مورد اعتبارسنجی باید به صورت آدرس ایمیل فرمت دهی شود.

exists:table,column

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

استفاده (نمونه ی ساده) از قانون اعتبارسنجی exists

                    'state' => 'exists:states'

تعریف یک اسم سفارشی برای ستون

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

می توانید شرط های بیشتری را اعمال کنید. این شرط ها در قالب عبارت های "where" به query مورد نظر اضافه می شوند:

                    'email' => 'exists:staff,email,account_id,1'

این شرط ها را می توان با استفاده از عملگر "!" نقیض نمود:

                    'email' => 'exists:staff,email,role,!admin'

همچنین می توانید NULL یا NOT_NULL را به دستور شرطی "where" ارسال نمایید:

'email' => 'exists:staff,email,deleted_at,NULL'
'email' => 'exists:staff,email,deleted_at,NOT_NULL'

می توانید یک database connection مشخص برای استفاده ی کوئری exists (جهت بررسی و تصدیق وجود یک فیلد معین در جدول) تعیین کنید. برای این منظور کافی است اسم connection مورد نظر را به وسیله ی عملگر نقطه به ابتدای اسم جدول الصاق نمایید:

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

filled

<

فیلد مورد اعتبارسنجی (در صورت حضور) نباید تهی باشد.

image

فایل مورد اعتبارسنجی باید فایل تصویری با فرمت jpeg، png، bmp، gif یا svg باشد.

in:foo,bar,...

فیلد مورد اعتبارسنجی باید داخل لیست مقادیر ارائه شده موجود باشد.

in_array:anotherfield

فیلد مورد اعتبارسنجی باید داخل مقادیر anotherfield موجود باشد.

integer

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

ip

فیلد مورد اعتبارسنجی باید با فرمت یک آدرس IP باشد.

json

فیلد مورد اعتبار سنجی باید یک رشته ی مجاز با فرمت JSON باشد.

max:value

فیلد مورد اعتبارسنجی باید دارای مقداری کوچکتر یا مساوی (مقدار) value بیشینه یا ماکسیسم باشد. مقادیر رشته ای، عددی و فایل ها همگی به شیوه ی تعریف شده توسط قانون اعتبارسنجی size ارزیابی و درست سنجی می شوند.

mimetypes:text/plain,...

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

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

به منظور شناسایی نوع MIME فایل آپلود شده، محتویات فایل خوانده شده و در پی آن فریم ورک سعی می کند نوع MIME را حدس بزند (نوعMIME ممکن است با نوع MIME ارائه شده توسط کلاینت فرق داشته باشد).

mimes:foo,bar,...

نوع MIME فایل (نوع فایل) مورد اعتبار سنجی باید با یکی از پسوندهای (extension) لیست شده منطبق باشد.

استفاده ی ساده از قانون اعتبارسنجی MIME

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

در سنجش اعتبار با این معیار، ارائه ی پسوند فایل کفایت می کند. اما بد نیست بدانید که معیار مزبور محتویات فایل را کامل می خواند و از این طریقMIME type را تشخیص داده و نوع فایل را اعتبارسنجی می کند.

min:value

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

not_in:foo,bar,...

فیلد مورد اعتبارسنجی نباید داخل لیست مقادیر ارائه شده وجود داشته باشد.

numeric

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

present

فیلد مورد سنجش اعتبار باید در داده های ورودی موجود باشد اما اشکالی ندارد تهی باشد (مقداری در آن وارد نشود).

regex:pattern

فیلد مورد اعتبار سنجی بایستی با الگوی regular expression ارائه شده منطبق باشد.

required

فیلد مورد اعتبارسنجی بایستی علاوه بر موجود بودن در داده های ورودی، تهی نیز نباشد. یک فیلد زمانی تهی یا "empty" تلقی می شود که یکی از شرایط زیر صادق باشد:

1. مقدار null باشد.
2. مقدار یک رشته ی تهی باشد.
3. مقدار مورد نظر یک آرایه ی تهی یا شی Countable باشد.
4. مقدار مورد نظر فایل آپلود شده ای باشد که هیچ مسیری برای آن مشخص نشده است (path نداشته باشد).

required_if:anotherfield,value,...

در صورتی که مقدار فیلد anotherfield برابر با هر value ای باشد، فیلدی که اعتبار سنجی می شود می بایست در مقادیر ورودی موجود باشد.

required_unless:anotherfield,value,...

فیلدی که سنجش اعتبار می شود باید در ورودی ها حاضر باشد مگر اینکه مقدار فیلد anotherfield برابر با هر valueای باشد. در واقع تنها در صورتی که مقدار فیلد anotherfield برابر با هر value ای باشد، فیلد مورد اعتبارسنجی نباید در ورودی ها باشد.

required_with:foo,bar,...

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

required_with_all:foo,bar,...

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

required_without:foo,bar,...

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

required_without_all:foo,bar,...

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

same:field

فیلد ارائه شده باید با فیلد مورد اعتبارسنجی همخوانی داشته باشد.

size:value

فیلد مورد اعتبارسنجی بایستی سایزی برابر با مقدار value ارائه شده داشته باشد. برای مقادیر رشته ای، value باید با تعداد کاراکتر همخوانی داشته باشد (سایز به تعداد کاراکترهای موجود در رشته اشاره دارد). در خصوص مقادیر عددی، value به مقدار عدد صحیح مشخص اشاره دارد. برای فایل ها نیز size به حجم فایل بر حسب کیلوبایت اشاره دارد.

string

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

timezone

فیلد مورد اعتبارسنجی باید بر اساس تابع timezone_identifiers_list زبان PHP دارای شناسه ی ناحیه ی زمانی (timezone id) معتبر باشد.

unique:table,column,except,idColumn

فیلدی که اعتبارسنجی می شود باید در جدول مورد نظر در پایگاه داده یگانه باشد. اگر آپشن column مشخص نشود، اسم فیلد جایگزین آن خواهد شد.

مشخص کردن اسم اختصاصی برای ستون:

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

database connection اختصاصی

گاهی لازم می شود برای query هایی که validator برای پرس و جو از پایگاه داده می سازد، connection اختصاصی تنظیم کنید. همان طور که در بالا مشاهده شد، اگر unique:users را به عنوان معیار اعتبارسنجی انتخاب کنید، در آن صورت از database connection پیش فرض برای کوئری گرفتن و پرس و جو از پایگاه داده استفاده می شود. برای بازنویسی این روال، connection دلخواه را درج و به دنبال آن عملگر نقطه و اسم جدول را مشخص می کنیم:

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

اعمال قانون اعتبارسنجی unique و نادیده گرفتن ID مشخص (اعمال unique بر روی تمامی مشخصات و جزئیات به استثنای ID)

گاهی ممکن است لازم شود یک ID معین را در اعتبارسنجی با معیار سنجش unique نادیده بگیرید (به عبارت دیگر، id مشمول اعتبار سنجی نشود). برای مثال یک صفحه ی بروز رسانی مشخصات کاربر را در نظر بگیرید که اسم، محل سکونت، آدرس ایمیل کاربر سایت را شامل می شود. قطعا می خواهید مطمئن شوید آدرس ایمیل کاربر منحصربفرد باشد. سناریویی را در نظر بگیرید که در آن کاربر تنها فیلد name را تغییر داده و فیلد e-mailرا ویرایش نمی کند. در این صورت یک خطای اعتبارسنجی صادر می شود و شما نمی خواهید تنها به این خاطر که کاربر از قبل مالک ایمیل مورد نظر است خطا رخ دهد. بلکه می خواهید تنها زمانی که کاربر یک آدرس ایمیل تکراری (مورد استفاده ی کاربر دیگری) را وارد کرد، خطای سنجش اعتبار رخ دهد. برای اینکه به قانون اعتبارسنجی اعلان کنیم که ID کاربر مورد نظر را نادیده بگیرد، می توان ID را به عنوان آرگومان سوم پاس داد:

                    'email' => 'unique:users,email_address,'.$user->id

اگر اسم ستون کلید اصلی (primary key) جدول id نباشد، می توانید آن اسم را به عنوان پارامتر چهارم ارسال کنید:

                    'email' => 'unique:users,email_address,'.$user->id.',user_id'

افزودن شرط های بیشتر در قالب عبارت های Where:

می توانید شرطهای بیشتری تعریف کنید که مانند شرط های where به کوئری اضافه می شوند:

                    'email' => 'unique:users,email_address,NULL,id,account_id,1'

url

فیلدی که اعتبار سنجی می شود باید بر اساس تابعfilter_var زبان PHP یک URL معتبر (دارای فرمت یک URL صحیح) باشد.

افزودن مشروط معیارهای اعتبارسنجی

گاهی مایلید اعتبارسنجی تنها زمانی بر روی یک فیلد انجام شود که آن فیلد در آرایه ی ورودی موجود باشد. برای نیل به این هدف کافی است معیار سنجش اعتبار sometimes را به لیست قوانین (rule list) خود اضافه نمایید:

$v = Validator::make($data, [
   'email' => 'sometimes|required|email',
]);

در این مثال، فیلد email تنها زمانی اعتبارسنجی می شود که در آرایه ی $data موجود باشد:

اعتبارسنجی شرطی پیچیده

گاهی می خواهید قوانین اعتبارسنجی را بر اساس منطق شرطی پیچیده تری اعمال کنید. به عنوان مثال ممکن است بخواهید یک فیلد تنها زمانی که فیلد دیگری مقدارش بزرگتر از 100 بود، الزامی شود. یا لازم داشته باشید فیلدی معین تنها زمانی وجود داشته باشد که دو فیلد دیگر با مقدار مشخص وجود داشته باشند. افزودن این قوانین اعتبارسنجی با لاراول بسیار آسان می باشد. ابتدا یک نمونه از کلاس Validator با قوانین ثابت شخصی خود تعریف نمایید:

$v = Validator::make($data, [
   'email' => 'required|email',
   'games' => 'required|numeric',
]);

فرض بگیرید برنامه ی تحت وب ما ویژه ی صاحبان کلکسیون بازی طراحی شده است. در صورتی که کاربر (کلکسیونر بازی) در اپلیکیشن ما ثبت نام کرده و نیز بیش از 100 بازی داشته باشد، از او می خواهیم دلیل جمع آوری این تعداد بازی را شرح دهد. برای مثال ممکن است این کاربر یک فروشگاه ارائه بازی را اداره می کند یا صرفا از این کار لذت می برد. به منظور افزودن این ملزومات به صورت مشروط همزمان برای چندین فیلد، می توان متدsometimes را در نمونه ی ایجاد شده از کلاس validator فراخوانی کرد:

$v->sometimes('reason', 'required|max:500', function($input) {
   return $input->games >= 100;
});

اولین آرگومان ارسالی به متد نام برده، اسم فیلدی است که به صورت شرطی اعتبار سنجی می کنیم. دومین آرگومان قوانینی است که می خواهیم اضافه کنیم. اگر تابع Closure پاس داده شده به عنوان آرگومان سوم، مقدار بولی true را برگرداند، در آن صورت قوانین اعتبارسنجی با موفقیت اضافه می شوند. این روش فرایند ساخت اعتبارسنجی های پیچیده را بسیار آسان می کند. در صورت لزوم می توان چندین اعتبارسنجی شرطی را همزمان به چند فیلد اضافه کرد:

$v->sometimes(['reason', 'cost'], 'required', function($input) {
   return $input->games >= 100;
});

معیارها و قوانین اعتبارسنجی سفارشی شده

Laravel مجموعه ای غنی از قوانین اعتبارسنجی کارامد را ارائه می دهد. با این حال گاهی لازم است قوانین اختصاصی خود را تعریف کنید. یکی از روش های ثبت قوانین اعتبارسنجی سفارشی، استفاده از متد extend در Validator façade می باشد. حال این متد را در یک service providerبرای ثبت قانون اعتبارسنجی اختصاصی خود بکار می بریم:

<?php
namespace App\Providers;
use Validator;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
   /**
    * Bootstrap any application services.
    *
    * @return void
    */
   public function boot()
   {
       Validator::extend('foo', function($attribute, $value, $parameters, $validator) {
           return $value == 'foo';
       });
   }
   /**
    * Register the service provider.
    *
    * @return void
    */
   public function register()
   {
       //
   }
}

تابع Closure چهار آرگومان دریافت می کند:

1. اسم $attribute که اعتبارسنجی می شود
2. $value آن attributeای که اعتبار و درستی آن سنجیده می شود
3. آرایه ای از $parameters که به قانون اعتبارسنجی ارسال می شود
4. نمونه ای از کلاس Validator.

می توانید بجای Closure یک کلاس و متد به تابع extend ارسال نمایید:

                    Validator::extend('foo', 'FooValidator@validate');

تعریف پیغام خطا برای قانون اعتبارسنجی اختصاصی

مسلما باید برای قانون اعتبارسنجی سفارشی خود یک پیغام خطا تنظیم کنید. برای این منظور می توان پیغام را در قالب یک آرایه از پیغام های سفارشی درون خطی (inline) قرار داد یا آن را به عنوان یک ورودی جدید در داخل فایل اعتبارسنجی language درج کرد. پیغام خطای مورد نظر باید در اولین خط (level) آرایه قرار داده شود. به هیچ وجه این پیغام را در آرایه ی custom قرار ندهید چرا که این آرایه تنها ویژه ی پیغام های خطای مربوط بهattribute می باشد:

"foo" => "Your input was invalid!",
"accepted" => "The :attribute must be accepted.",
// The rest of the validation error messages...

زمانی که یک قانون اعتبارسنجی جدید ایجاد می کنید، می توانید برای پیام های خطای (جایگزین های custom) مکان نگهدار (place-holder) تعریف کنید. برای این منظور می توان یک نمونه ی اختصاصی از validator همان طور که در بالا تشریح شد ایجاد نموده، سپس متد replacer را در façade Validator فراخوانی کرد. این فراخوانی را می توان داخل بدنه ی متد boot از توابع service provider انجام داد:

/**
 * Bootstrap any application services.
 *
 * @return void
 */
public function boot()
{
   Validator::extend(...);
   Validator::replacer('foo', function($message, $attribute, $rule, $parameters) {
       return str_replace(...);
   });
}

implicit Extension

به طور پیش فرض، زمانی که یک attribute مورد سنجش اعتبار ناموجود است یا صرفا بخاطر معیار required دارای مقدار تهی باشد، در این صورت قوانین اعتبارسنجی معمول همچون custom extension ها اعمال نخواهند شد. برای مثال، معیار اعتبارسنجی unique بر روی مقدار null اجرا نخواهد شد:

$rules = ['name' => 'unique'];
$input = ['name' => null];
Validator::make($input, $rules)->passes();// true

برای اینکه یک قانون صرف نظر اینکه attribute مورد نظر فاقد مقدار است یا خیر، بر روی آن اجرا شود، قانون سنجش اعتبار باید به صورت ضمنی اعلان کند که آن attribute الزامی (required) است. برای رسیدن به این هدف، کافی است متد Validator::extendImplicit() را بکار ببرید:

Validator::extendImplicit('foo', function($attribute, $value, $parameters, $validator) {
   return $value == 'foo';
});