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

unchanged
Title
Reference: Model rules validation
unchanged
Category
Tutorials
changed
Tags
Form validation
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)[CModel] class uses a
method named
[rules](/doc/api/1.0.10/CModel#rules-detail)[CModel::rules()]
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)[Model::rules()]
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>:`attribute
list`: specifies the attributes (separated by commas) to be validated;
+ <code>validator name</code>:`validator
name`: specifies the validator to be used.
+ <code>on</code>:`on`: 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>:`message`: Error
message if validation fails.
+ <code>...validation
parameters...</code>:`...validation parameters...`: any
number of extra parameters to be used by the specified validator.

## Validation rules reference

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

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

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

+ <code>default</code>`default` :
[CDefaultValueValidator](/doc/api/CDefaultValueValidator),[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>,`setOnEmpty`,
whether to set the default value only when the attribute value is null or empty
string.
2. <code>value</code>,`value`, the default
value to be set to the specified attributes.

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

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

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

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

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

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

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

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

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

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

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

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

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

+ <code>url</code>`url` :
[CUrlValidator](/doc/api/CUrlValidator),[CUrlValidator],
validates that the attribute value is a valid http or https URL.
1. <code>allowEmpty</code>,`allowEmpty`,
whether the attribute value can be null or empty.
2. <code>pattern</code>,`pattern`, 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::validate()]<br
/>
[CModel::rules()](/doc/api/CModel#rules-detail)<br
[CModel::rules()]<br />
[CModel::$scenario](/doc/api/CModel#scenario-detail)<br
[CModel::$scenario]<br />
[CValidator](/doc/api/CValidator)<br
[CValidator]<br />
[CInlineValidator](/doc/api/CInlineValidator)
[CInlineValidator]

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