You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
210 lines
9.4 KiB
210 lines
9.4 KiB
11 years ago
|
Model validation reference
|
||
|
==========================
|
||
|
|
||
11 years ago
|
As a model both represents data and defines the business rules to which that data must adhere, comprehending data validation is key to using Yii. In order to learn model validation basics, please refer to [Model, Validation subsection](model.md#Validation).
|
||
|
|
||
|
This guide describes all of Yii's validators and their parameters.
|
||
|
|
||
11 years ago
|
|
||
|
Standard Yii validators
|
||
|
-----------------------
|
||
|
|
||
11 years ago
|
The standard Yii validators are defined in many Yii classes, found primarily within the `yii\validators` namespace. But you do not need to specify the full namespace for the standard Yii validators as Yii can recognize them from defined aliases.
|
||
|
|
||
|
Here's the list of all validators bundled with the Yii framework, including their most useful properties. The default value for each property is indicated in parentheses. Note that this does not present an exhaustive list of each validator's properties.
|
||
11 years ago
|
|
||
11 years ago
|
### `boolean`: [[yii\validators\BooleanValidator|BooleanValidator]]
|
||
11 years ago
|
|
||
|
Checks if the attribute value is a boolean value.
|
||
|
|
||
|
- `trueValue`, the value representing true status. _(1)_
|
||
|
- `falseValue`, the value representing false status. _(0)_
|
||
11 years ago
|
- `strict`, whether to also compare the type of the value and `trueValue`/`falseValue`. _(false)_
|
||
11 years ago
|
|
||
11 years ago
|
### `captcha`: [[yii\captcha\CaptchaValidator|CaptchaValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is the same as the verification code displayed in the CAPTCHA. Should be used together
|
||
11 years ago
|
with [[yii\captcha\CaptchaAction]].
|
||
11 years ago
|
|
||
11 years ago
|
- `caseSensitive`, whether the comparison is case sensitive. _(false)_
|
||
|
- `captchaAction`, the route of the controller action that renders the CAPTCHA image. _('site/captcha')_
|
||
11 years ago
|
|
||
11 years ago
|
### `compare`: [[yii\validators\CompareValidator|CompareValidator]]
|
||
11 years ago
|
|
||
|
Compares the specified attribute value with another value and validates if they are equal.
|
||
|
|
||
11 years ago
|
- `compareAttribute`, the name of the attribute to be compared with. _(currentAttributeName_repeat)_
|
||
|
- `compareValue`, a constant value to be compared with.
|
||
|
- `operator`, the operator for the comparison. _('==')_
|
||
11 years ago
|
|
||
11 years ago
|
### `date`: [[yii\validators\DateValidator|DateValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Verifies if the attribute represents a date, time, or datetime in a proper format.
|
||
11 years ago
|
|
||
11 years ago
|
- `format`, the date format that the value being validated should follow according to
|
||
11 years ago
|
[PHP date_create_from_format](http://www.php.net/manual/en/datetime.createfromformat.php). _('Y-m-d')_
|
||
11 years ago
|
- `timestampAttribute`, the name of the attribute that should receive the parsed result.
|
||
11 years ago
|
|
||
11 years ago
|
### `default`: [[yii\validators\DefaultValueValidator|DefaultValueValidator]]
|
||
11 years ago
|
|
||
|
Sets the attribute to be the specified default value.
|
||
|
|
||
11 years ago
|
- `value`, the default value to be assigned.
|
||
11 years ago
|
|
||
11 years ago
|
### `double`: [[yii\validators\NumberValidator|NumberValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Validates that the attribute value is a number, integer or decimal.
|
||
11 years ago
|
|
||
11 years ago
|
- `max`, the upper limit of the number (inclusive). _(null)_
|
||
|
- `min`, the lower limit of the number (inclusive). _(null)_
|
||
11 years ago
|
|
||
11 years ago
|
### `email`: [[yii\validators\EmailValidator|EmailValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Validates that the attribute value is a valid email address. By default, this validator checks if the attribute value is a syntactical valid email address, but the validator can be configured to check the address's domain for the address's existence.
|
||
11 years ago
|
|
||
11 years ago
|
- `allowName`, whether to allow the name in the email address (e.g. `John Smith <john.smith@example.com>`). _(false)_.
|
||
|
- `checkMX`, whether to check the MX record for the email address. _(false)_
|
||
|
- `checkPort`, whether to check port 25 for the email address. _(false)_
|
||
|
- `enableIDN`, whether the validation process should take into account IDN (internationalized domain names). _(false)_
|
||
11 years ago
|
|
||
11 years ago
|
### `exist`: [[yii\validators\ExistValidator|ExistValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value exists in a table.
|
||
|
|
||
11 years ago
|
- `targetClass`, the ActiveRecord class name or alias of the class that should be used to look for the attribute value being
|
||
11 years ago
|
validated. _(ActiveRecord class of the attribute being validated)_
|
||
11 years ago
|
- `targetAttribute`, the ActiveRecord attribute name that should be used to look for the attribute value being validated.
|
||
11 years ago
|
_(name of the attribute being validated)_
|
||
|
|
||
11 years ago
|
### `file`: [[yii\validators\FileValidator|FileValidator]]
|
||
11 years ago
|
|
||
|
Verifies if an attribute is receiving a valid uploaded file.
|
||
|
|
||
11 years ago
|
- `types`, an array of file name extensions that are allowed to be uploaded. _(any)_
|
||
|
- `minSize`, the minimum number of bytes required for the uploaded file.
|
||
|
- `maxSize`, the maximum number of bytes allowed for the uploaded file.
|
||
|
- `maxFiles`, the maximum number of files that the given attribute can hold. _(1)_
|
||
11 years ago
|
|
||
11 years ago
|
### `filter`: [[yii\validators\FilterValidator|FilterValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Converts the attribute value by sending it through a filter.
|
||
11 years ago
|
|
||
11 years ago
|
- `filter`, a PHP callback that defines a filter.
|
||
11 years ago
|
|
||
|
Typically a callback is either the name of PHP function:
|
||
|
|
||
|
```php
|
||
11 years ago
|
['password', 'filter', 'filter' => 'trim'],
|
||
11 years ago
|
```
|
||
|
|
||
|
Or an anonymous function:
|
||
|
|
||
|
```php
|
||
11 years ago
|
['text', 'filter', 'filter' => function ($value) {
|
||
11 years ago
|
// here we are removing all swear words from text
|
||
|
return $newValue;
|
||
11 years ago
|
}],
|
||
11 years ago
|
```
|
||
|
|
||
11 years ago
|
### `in`: [[yii\validators\RangeValidator|RangeValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is among a list of values.
|
||
|
|
||
11 years ago
|
- `range`, a list of valid values that the attribute value should be among (inclusive).
|
||
|
- `strict`, whether the comparison should be strict (both the type and value must be the same). _(false)_
|
||
|
- `not`, whether to invert the validation logic. _(false)_
|
||
11 years ago
|
|
||
11 years ago
|
### `inline`: [[yii\validators\InlineValidator|InlineValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Uses a custom function to validate the attribute. You need to define a public method in your
|
||
11 years ago
|
model class that will evaluate the validity of the attribute. For example, if an attribute
|
||
|
needs to be divisible by 10, in the rules you would define: `['attributeName', 'isDivisibleByTen']`.
|
||
11 years ago
|
|
||
|
Then, your own method could look like this:
|
||
11 years ago
|
|
||
11 years ago
|
```php
|
||
11 years ago
|
public function isDivisibleByTen($attribute) {
|
||
11 years ago
|
if (($this->$attribute % 10) != 0) {
|
||
11 years ago
|
$this->addError($attribute, 'cannot divide value by 10');
|
||
|
}
|
||
|
}
|
||
|
```
|
||
|
|
||
11 years ago
|
### `integer`: [[yii\validators\NumberValidator|NumberValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Validates that the attribute value is an integer.
|
||
11 years ago
|
|
||
11 years ago
|
- `max`, the upper limit of the number (inclusive). _(null)_
|
||
|
- `min`, the lower limit of the number (inclusive). _(null)_
|
||
11 years ago
|
|
||
11 years ago
|
### `match`: [[yii\validators\RegularExpressionValidator|RegularExpressionValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Validates that the attribute value matches the specified pattern defined by a regular expression.
|
||
11 years ago
|
|
||
11 years ago
|
- `pattern`, the regular expression to be matched.
|
||
|
- `not`, whether to invert the validation logic. _(false)_
|
||
11 years ago
|
|
||
11 years ago
|
### `number`: [[yii\validators\NumberValidator|NumberValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is a number.
|
||
|
|
||
11 years ago
|
- `max`, the upper limit of the number (inclusive). _(null)_
|
||
|
- `min`, the lower limit of the number (inclusive). _(null)_
|
||
11 years ago
|
|
||
11 years ago
|
### `required`: [[yii\validators\RequiredValidator|RequiredValidator]]
|
||
11 years ago
|
|
||
11 years ago
|
Validates that the specified attribute does not have a null or empty value.
|
||
11 years ago
|
|
||
11 years ago
|
- `requiredValue`, the desired value that the attribute must have. _(any)_
|
||
|
- `strict`, whether the comparison between the attribute value and
|
||
|
[[yii\validators\RequiredValidator::requiredValue|requiredValue]] must match both value and type. _(false)_
|
||
11 years ago
|
|
||
11 years ago
|
### `safe`: [[yii\validators\SafeValidator|SafeValidator]]
|
||
11 years ago
|
|
||
|
Serves as a dummy validator whose main purpose is to mark the attributes to be safe for massive assignment.
|
||
|
|
||
11 years ago
|
### `string`: [[yii\validators\StringValidator|StringValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is of certain length.
|
||
|
|
||
11 years ago
|
- `length`, specifies the length limit of the value to be validated (inclusive). Can be `exactly X`, `[min X]`, `[min X, max Y]`.
|
||
|
- `max`, the upper length limit (inclusive). If not set, it means no maximum length limit.
|
||
|
- `min`, the lower length limit (inclusive). If not set, it means no minimum length limit.
|
||
|
- `encoding`, the encoding of the string value to be validated. _([[yii\base\Application::charset]])_
|
||
11 years ago
|
|
||
11 years ago
|
### `unique`: [[yii\validators\UniqueValidator|UniqueValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is unique in the corresponding database table.
|
||
|
|
||
11 years ago
|
- `targetClass`, the ActiveRecord class name or alias of the class that should be used to look for the attribute value being
|
||
11 years ago
|
validated. _(ActiveRecord class of the attribute being validated)_
|
||
11 years ago
|
- `targetAttribute`, the ActiveRecord attribute name that should be used to look for the attribute value being validated.
|
||
11 years ago
|
_(name of the attribute being validated)_
|
||
|
|
||
11 years ago
|
### `url`: [[yii\validators\UrlValidator|UrlValidator]]
|
||
11 years ago
|
|
||
|
Validates that the attribute value is a valid http or https URL.
|
||
|
|
||
11 years ago
|
- `validSchemes`, an array of URI schemes that should be considered valid. _['http', 'https']_
|
||
|
- `defaultScheme`, the default URI scheme. If the input doesn't contain the scheme part, the default scheme will be
|
||
11 years ago
|
prepended to it. _(null)_
|
||
11 years ago
|
- `enableIDN`, whether the validation process should take into account IDN (internationalized domain names). _(false)_
|
||
11 years ago
|
|
||
|
Validating values out of model context
|
||
|
--------------------------------------
|
||
|
|
||
11 years ago
|
Sometimes you need to validate a value that is not bound to any model, such as a standalone email address. The `Validator` class has a
|
||
|
`validateValue` method that can help you in these scenarios. Not all validator classes have implemented this method, but the ones that have implemented `validateValue` can be used without a model. For example, to validate an email stored in a string, you can do the following:
|
||
11 years ago
|
|
||
|
```php
|
||
|
$email = 'test@example.com';
|
||
|
$validator = new yii\validators\EmailValidator();
|
||
11 years ago
|
if ($validator->validate($email, $error)) {
|
||
11 years ago
|
echo 'Email is valid.';
|
||
11 years ago
|
} else {
|
||
11 years ago
|
echo $error;
|
||
11 years ago
|
}
|
||
|
```
|
||
11 years ago
|
|
||
11 years ago
|
TBD: refer to http://www.yiiframework.com/wiki/56/ for the format
|