laravel/documentation/start/validation.md

Validation

• The Basics
• Validation Rules
• Retrieving Error Messages
• Specifying Custom Error Messages
• Creating Custom Validation Rules

The Basics

Almost every interactive web application needs to validate data. For instance, a registration form probably requires the password to be confirmed. Maybe the e-mail address must be unique. Validating data can be a cumbersome process. Thankfully, it isn't in Laravel. The Validator class provides as awesome array of validation helpers to make validating your data a breeze.

To get started, let's imagine we have the following array:

$array = array('name' => 'Taylor', 'email' => 'example@gmail.com');

Next, we're ready to define validation rules for our array:

$rules = array(
    'name'  => array('required', 'max:50'),
    'email' => array('required', 'email', 'unique:users'),
);

If you don't like using arrays, you may also delimit rules using a pipe character:

$rules = array(
    'name'  => 'required|max:50',
    'email' => 'required|email|unique:users',
);

Great! Now we're ready to make a Validator instance and validate our array:

$validator = Validator::make($array, $rules);

if ( ! $validator->valid())
{
    return $validator->errors;
}

Via the errors property, you can access a simple error collector class that makes working with your error messages a breeze. Of course, default error messages have been setup for all validation rules. The default messages live in the application/lang/en/validation.php file.

Now you are familiar with the basic usage of the Validator class. You're ready to dig in and learn about the rules you can use to validate your data!

Validation Rules

• Required
• Alpha, Alpha Numeric, & Alpha Dash
• Size
• Numericality
• Inclusion & Exclusion
• Confirmation
• Acceptance
• Uniqueness
• E-Mail Addresses
• URLs
• Uploads

Required

The required rule validates that an attribute is present in the array and is not an empty string:

$rules = array(
    'name' => 'required',
);

Alpha, Alpha Numeric, & Alpha Dash

The alpha rule validates that an attribute consists solely of letters:

$rules = array(
    'name' => 'alpha',
);

The alpha_num rule validates that an attribute consists solely of letters and numbers:

$rules = array(
    'username' => 'alpha_num',
);

The alpha_dash rule validates that an attribute consists solely of letters, numbers, dashes, and underscores:

$rules = array(
    'username' => 'alpha_dash',
);

Size

The size rule validates that an attribute is of a given length, or, if the attribute is numeric, is a given value:

$rules = array(
    'name' => 'size:10',
);

The between rule validates that an attribute is between a given minimum and maximum:

$rules = array(
    'payment' => 'between:10,50',
);

Note: All minimum and maximum checks are inclusive.

The min rule validates that an attribute is greater than or equal to a given value:

$rules = array(
    'payment' => 'min:10',
);

The max rule validates that an attribute is less than or equal to a given value:

$rules = array(
    'payment' => 'max:50',
);

Numericality

The numeric rule validates that an attribute is (surprise!) numeric:

$rules = array(
    'payment' => 'numeric',
);

The integer rule validates that an attribute is an integer:

$rules = array(
    'payment' => 'integer',
);

Inclusion & Exclusion

The in rule validates that an attribute is contained in a list of values:

$rules = array(
    'size' => 'in:small,medium,large',
);

The not_in rule validates that an attribute is not contained in a list of values:

$rules = array(
    'language' => 'not_in:cobol,assembler',
);

Confirmation

The confirmed rule validates that, for a given attribute, a matching attribute_confirmation attribute exists. For example, given the following rule:

$rules = array(
    'password' => 'confirmed',
);

The Validator will make sure that the password attribute matches the password_confirmation attribute in the array being validated.

Acceptance

The accepted rule validates that an attribute is equal to yes or 1. This rule is helpful for validating checkbox form fields such as "terms of service".

$rules = array(
    'terms' => 'accepted',
);

Uniqueness

The unique rule validates the uniqueness of an attribute on a given database table:

$rules = array(
    'email' => 'unique:users',
);

In the example above, the email attribute will be checked for uniqueness on the users table. Need to verify uniqueness on a column name other than the attribute name? No problem:

$rules = array(
    'email' => 'unique:users,email_address',
);

E-Mail Addresses

The email rule validates that an attribute contains a correctly formatted e-mail address:

$rules = array(
    'email' => 'email',
);

URLs

The url rule validates that an attribute contains a correctly formatted URL:

$rules = array(
    'link' => 'url',
);

The active_url rule uses the PHP checkdnsrr function to verify that a URL is active:

$rules = array(
    'link' => 'active_url',
);

Uploads

The mimes rule validates that an uploaded file has a given MIME type. This rule uses the PHP Fileinfo extension to read the contents of the file and determine the actual MIME type. Any extension defined in the application/config/mimes.php file may be passed to this rule as a parameter:

$rules = array(
    'picture' => 'mimes:jpg,gif',
);

$validator = Validator::make(Input::file(), $rules);

Need to validate form data and upload data at the same time? Use the all method on the Input class to get form and upload data in one array:

$validator = Validator::make(Input::all(), $rules);

The image rule validates that an uploaded file has a jpg, gif, bmp, or png MIME type:

$rules = array(
    'picture' => 'image',
);

You may also validate the size of an upload using the max rule. Simply specify the maximum number of kilobytes the upload may be:

$rules = array(
    'picture' => 'image|max:100',
);

Retrieving Error Messages

Laravel makes working with your error messages a cinch using a simple error collector class. After calling the valid or invalid method on a Validator instance, you may access the errors via the errors property:

if ( ! $validator->valid())
{
    return $validator->errors;
}

The error collector has the following simple functions for retrieving your error messages: has, first, get, and all.

The has method will check if an error message exists for a given attribute:

if ($validator->errors->has('email'))
{
    // The e-mail attribute has errors...
}

The first method will return the first error message for a given attribute:

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

Sometimes you may need to format the error message by wrapping it in HTML. No problem. Along with the :message place-holder, pass the format as the second parameter to the method:

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

The get method returns an array containing all of the error messages for a given attribute:

return $validator->errors->get('email');

return $validator->errors->get('email', '<p>:message</p>');

The all method returns an array containing all error messages for all attributes:

return $validator->errors->all();

return $validator->errors->all('<p>:message</p>');

Specifying Custom Error Messages

Want to use an error message other than the default? Maybe you even want to use a custom error message for a given attribute and rule. Either way, the Validator class makes it easy.

Simply create an array of custom messages to pass to the Validator instance:

$messages = array(
    'required' => 'The :attribute field is required.',
);

$validator = Validator::make(Input::get(), $rules, $messages);

Great! Now our custom message will be used anytime a required validation check fails. But, what is this :attribute stuff in our message? To make your life easier, the Validator class will replace the :attribute place-holder with the actual name of the attribute! It will even remove underscores from the attribute name.

You may also use the :size, :min, :max, and :values place-holders when constructing your error messages:

$messages = array(
    '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',
);

So, what if you need to specify a custom required message, but only for the email attribute? No problem. Just specify the message using an attribute_rule naming convention:

$messages = array(
    'email_required' => 'We need to know your e-mail address!',
);

In the example above, the custom required message will be used for the email attribute, while the default message will be used for all other attributes.

Creating Custom Validation Rules

Need to create your own validation rules? You will love how easy it is! First, create a class that extends System\Validator and place it in your application/libraries directory:

<?php

class Validator extends System\Validator {}

Next, remove the Validator alias from application/config/aliases.php.

Alright! You're ready to define your own validation rule. Create a function on your new validator using a validate_rule naming convention. Validator methods simply need to return true or false. It couldn't be any easier, right?

<?php

class Validator extends System\Validator {

    public function validate_awesome($attribute, $parameters)
    {
        return $attribute == 'awesome';
    }

}

Let's dig into this example. The validate_awesome function receives two arguments. The first is the value of the attribute being validated, the second is an array of parameters that were specified for the rule, such as a size or list of accepted values (more on that in a second).

Now, how do you use your new validator? It's refreshingly simple:

$rules = array(
    'username' => 'required|awesome',
);

Of course, you will need to define an error message for your new rule. You can do this either in an ad-hoc messages array:

$messages = array(
    'awesome' => 'The attribute value must be awesome!',
);

$validator = Validator::make(Input::get(), $rules, $messages);

Or by adding an entry for your rule in the application/lang/en/validation.php file:

'awesome' => 'The attribute value must be awesome!',

As mentioned above, you may even specify and receive a list of parameters in your custom validator:

// When building your rules array...

$rules = array(
    'username' => 'required|awesome:yes',
);

// In your custom validator...

class Validator extends System\Validator {

    public function validate_awesome($attribute, $parameters)
    {
        return $attribute == $parameters[0];
    }

}

In this case, the parameters argument of your validation rule would receive an array containing one element: "yes".