Difference between #3 and #2 of Reference: Model rules validation

unchanged
Title
Reference: Model rules validation
unchanged
Category
Tutorials
unchanged
Tags
changed
Content
This is a reference to be used for Model rule validation and is compiled from
the Yii documentation and code. The purpose is to have all the information
gathered in one place instead of scattered. This reference is not an intro.

Applys to Yii: 1.0.10

## How validation works
The [CModel](/doc/api/1.0.10/CModel) class uses a method named
[rules](/doc/api/1.0.10/CModel#rules-detail) to return an array with the rules
for validation.

~~~
[php]
public function rules()
{
    return array(
        array('username, password', 'required'),
        array('password_repeat', 'required', 'on'=>'register'),
        array('password', 'compare', 'on'=>'register'),
    );
}
~~~

The code above is an example of what the [rules()](/doc/api/CModel#rules-detail)
function may look like. The arrays in the main array each one sets a rule of
validation. 

### Choise of validators

Yii will look for validators in the specifik order:

1. A method in the model class with the same name as the validator specified.
2. A builtin validator in Yii that extends the CValidator class.
3. A path/alias to a home made  CValidator class that is not built in.

### Scenarios

TODO: Write shortly about scenarios.

### Standard parameters

~~~
[php]
array(
	'attribute list', 
	'validator name', 
	'on'=>'scenario name', 
	'message'=>'The attribute didn\'t validate!', 
	...validation parameters...
);
~~~

+ <code>attribute list</code>: specifies the attributes (separated
by commas) to be validated;
+ <code>validator name</code>: specifies the validator to be used.
+ <code>on</code>: this specifies the scenarios when the validation
rule should be performed. Separate different scenarios with commas. If this
option is not set, the rule will be applied in any scenario.
+ <code>message</code>: Error message if validation fails.
+ <code>...validation parameters...</code>: any number of extra
parameters to be used by the specified validator.

## Validation rules reference

+ <code>boolean</code> :
[CBooleanValidator](/doc/api/CBooleanValidator)
+[CBooleanValidator](/doc/api/CBooleanValidator), validates that the
attribute value is either trueValue or falseValue.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
1. <code>falseValue</code>, the value representing false status.
1. <code>strict</code>, whether the comparison to trueValue and
falseValue is strict.
1. <code>trueValue</code>, the value representing true status.

+ <code>captcha</code> :
[CCaptchaValidator](/doc/api/CCaptchaValidator)
+[CCaptchaValidator](/doc/api/CCaptchaValidator), validates that the
attribute value is the same as the verification code displayed in the CAPTCHA.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>captchaAction</code>, ID of the action that renders the
CAPTCHA image.
3. <code>caseSensitive</code>, whether the comparison is case
sensitive.

+ <code>compare</code> :
[CCompareValidator](/doc/api/CCompareValidator)
+[CCompareValidator](/doc/api/CCompareValidator), compares the
specified attribute value with another value and validates if they are equal.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>compareAttribute</code>, the name of the attribute to be
compared with.
3. <code>compareValue</code>, the constant value to be compared
with.
4. <code>operator</code>, the operator for comparison.
5. <code>strict</code>, whether the comparison is strict (both value
and type must be the same.

+ <code>default</code> :
[CDefaultValueValidator](/doc/api/CDefaultValueValidator)
+[CDefaultValueValidator](/doc/api/CDefaultValueValidator), sets the
attributes with the specified value. It does not do validation. Its existence is
mainly to allow specifying attribute default values in a dynamic way.
1. <code>setOnEmpty</code>, whether to set the default value only
when the attribute value is null or empty string.
2. <code>value</code>, the default value to be set to the specified
attributes.

+ <code>email</code> :
[CEmailValidator](/doc/api/CEmailValidator)
+[CEmailValidator](/doc/api/CEmailValidator), validates that the
attribute value is a valid email address.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>allowName</code>, whether to allow name in the email
address. 
3. <code>checkMX</code>, whether to check the MX record for the
email address.
4. <code>checkPort</code>, whether to check port 25 for the email
address.
5. <code>fullPattern</code>, the regular expression used to validate
email addresses with the name part.
6. <code>pattern</code>, the regular expression used to validate the
attribute value.

+ <code>exists</code> :
[CExistValidator](/doc/api/CExistValidator)
+[CExistValidator](/doc/api/CExistValidator), validates that the
attribute value exists in a table.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>attributeName</code>, the ActiveRecord class attribute name
that should be used to look for the attribute value being validated.
3. <code>className</code>, the ActiveRecord class name that should
be used to look for the attribute value being validated.
4. <code>criteria</code>, additional query criteria.

+ <code>file</code> :
[CFileValidator](/doc/api/CFileValidator)
+[CFileValidator](/doc/api/CFileValidator), verifies if an attribute
is receiving a valid uploaded file.
1. <code>allowEmpty</code>, whether the attribute requires a file to
be uploaded or not.
2. <code>maxFiles</code>, the maximum file count the given attribute
can hold.
3. <code>maxSize</code>, the maximum number of bytes required for
the uploaded file.
4. <code>minSize</code>, the minimum number of bytes required for
the uploaded file.
5. <code>tooLarge</code>, the error message used when the uploaded
file is too large.
6. <code>tooMany</code>, the error message used if the count of
multiple uploads exceeds limit.
7. <code>tooSmall</code>,  	the error message used when the uploaded
file is too small.
8. <code>types</code>, a list of file name extensions that are
allowed to be uploaded.
9. <code>wrongType</code>, the error message used when the uploaded
file has an extension name that is not listed among extensions.

+ <code>filter</code> :
[CFilterValidator](/doc/api/CFilterValidator)
+[CFilterValidator](/doc/api/CFilterValidator), transforms the data
being validated based on a filter.
1. <code>filter</code>, the filter method.

+ <code>in</code> :
[CRangeValidator](/doc/api/CRangeValidator)
+[CRangeValidator](/doc/api/CRangeValidator), validates that the
attribute value is among the list (specified via range).
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>range</code>, list of valid values that the attribute value
should be among.
3. <code>strict</code>, whether the comparison is strict (both type
and value must be the same).

+ <code>length</code> :
[CStringValidator](/doc/api/CStringValidator)
+[CStringValidator](/doc/api/CStringValidator), validates that the
attribute value is of certain length.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>is</code>, exact length.
3. <code>max</code>, maximum length.
4. <code>min</code>, minimum length.
5. <code>tooLong</code>, user-defined error message used when the
value is too short.
6. <code>tooShort</code>, user-defined error message used when the
value is too long.

+ <code>numerical</code> :
[CNumberValidator](/doc/api/CNumberValidator)
+[CNumberValidator](/doc/api/CNumberValidator), validates that the
attribute value is a number.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>integerOnly</code>, whether the attribute value can only be
an integer.
3. <code>max</code>, upper limit of the number.
4. <code>min</code>, lower limit of the number.
5. <code>tooBig</code>, user-defined error message used when the
value is too big.
6. <code>tooSmall</code>, user-defined error message used when the
value is too small.

+ <code>match</code> :
[CRegularExpressionValidator](/doc/api/CRegularExpressionValidator)[CRegularExpressionValidator](/doc/api/CRegularExpressionValidator),
validates that the attribute value matches to the specified regular expression.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>pattern</code>, the regular expression to be matched with.

+ <code>required</code> :
[CRequiredValidator](/doc/api/CRequiredValidator), validates that the specified
attribute does not have null or empty value.
+1. <code>requiredValue</code>, the desired value
that the attribute must have.
2. <code>requiredValue</code>, whether the comparison to
requiredValue is strict.

+ <code>safe</code> :
[CSafeValidator](/doc/api/CSafeValidator)
+[CSafeValidator](/doc/api/CSafeValidator), marks the associated
attributes to be safe for massive assignments.

+ <code>type</code> :
[CTypeValidator](/doc/api/CTypeValidator)
+[CTypeValidator](/doc/api/CTypeValidator), verifies if the attribute
is of the type specified by type. (integer, float, string, date, time, datetime)
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>dateFormat</code>, the format pattern that the date value
should follow.
3. <code>datetimeFormat</code>, the format pattern that the datetime
value should follow.
4. <code>timeFormat</code>, the format pattern that the time value
should follow.
5. <code>type</code>, the data type that the attribute should be.

+ <code>unique</code> :
[CUniqueValidator](/doc/api/CUniqueValidator)
+[CUniqueValidator](/doc/api/CUniqueValidator), validates that the
attribute value is unique in the corresponding database table.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>attributeName</code>, the ActiveRecord class attribute name
that should be used to look for the attribute value being validated.
3. <code>caseSensitive</code>, whether the comparison is case
sensitive.
4. <code>className</code>, the ActiveRecord class name that should
be used to look for the attribute value being validated.
5. <code>criteria</code>, additional query criteria.

+ <code>unsafe</code> :
[CUnsafeValidator](/doc/api/CUnsafeValidator)
+[CUnsafeValidator](/doc/api/CUnsafeValidator), marks the associated
attributes to be unsafe so that they cannot be massively assigned.

+ <code>url</code> :
[CUrlValidator](/doc/api/CUrlValidator)[CUrlValidator](/doc/api/CUrlValidator),
validates that the attribute value is a valid http or https URL.
1. <code>allowEmpty</code>, whether the attribute value can be null
or empty.
2. <code>pattern</code>, the regular expression used to validates
the attribute value.

## Selected readings
[The Definitive Guide to Yii: Working with Forms - Creating
Model](/doc/guide/form.model)<br />
[CModel::validate()](/doc/api/CModel#validate-detail)<br />
[CModel::rules()](/doc/api/CModel#rules-detail)<br />
[CModel::$scenario](/doc/api/CModel#scenario-detail)<br />
[CValidator](/doc/api/CValidator)<br />
[CInlineValidator](/doc/api/CInlineValidator)

### Built in validators in Yii
[CBooleanValidator](/doc/api/CBooleanValidator)<br />
[CCaptchaValidator](/doc/api/CCaptchaValidator)<br />
[CCompareValidator](/doc/api/CCompareValidator)<br />
[CDefaultValueValidator](/doc/api/CDefaultValueValidator)<br />
[CEmailValidator](/doc/api/CEmailValidator)<br />
[CExistValidator](/doc/api/CExistValidator)<br />
[CFileValidator](/doc/api/CFileValidator)<br />
[CFilterValidator](/doc/api/CFilterValidator)<br />
[CNumberValidator](/doc/api/CNumberValidator)<br />
[CRangeValidator](/doc/api/CRangeValidator)<br />
[CRegularExpressionValidator](/doc/api/CRegularExpressionValidator)<br />
[CRequiredValidator](/doc/api/CRequiredValidator)<br />
[CSafeValidator](/doc/api/CSafeValidator)<br />
[CStringValidator](/doc/api/CStringValidator)<br />
[CTypeValidator](/doc/api/CTypeValidator)<br />
[CUniqueValidator](/doc/api/CUniqueValidator)<br />
[CUnsafeValidator](/doc/api/CUnsafeValidator)<br />
[CUrlValidator](/doc/api/CUrlValidator)