Validation reference, validators phpdoc fixes

docs/guide/validation.md

@@ -7,22 +7,176 @@ In order to learn model validation basics please refer to [Model, Validation sub
 Standard Yii validators
 -----------------------
 
-- `boolean`: [[BooleanValidator]]
+Standard Yii validators could be specified using aliases instead of referring to class names. Here's the list of all
-- `captcha`: [[CaptchaValidator]]
+validators budled with Yii with their most useful properties:
-- `compare`: [[CompareValidator]]
+
-- `date`: [[DateValidator]]
+### `boolean`: [[BooleanValidator]]
-- `default`: [[DefaultValueValidator]]
+
-- `double`: [[NumberValidator]]
+Checks if the attribute value is a boolean value.
-- `email`: [[EmailValidator]]
+
-- `exist`: [[ExistValidator]]
+- `trueValue`, the value representing true status. _(1)_
-- `file`: [[FileValidator]]
+- `falseValue`, the value representing false status. _(0)_
-- `filter`: [[FilterValidator]]
+- `strict`, whether to compare the type of the value and `trueValue`/`falseValue`. _(false)_
-- `in`: [[RangeValidator]]
+
-- `integer`: [[NumberValidator]]
+### `captcha`: [[CaptchaValidator]]
-- `match`: [[RegularExpressionValidator]]
+
-- `required`: [[RequiredValidator]]
+Validates that the attribute value is the same as the verification code displayed in the CAPTCHA. Should be used together
-- `string`: [[StringValidator]]
+with [[CaptchaAction]].
-- `unique`: [[UniqueValidator]]
+
-- `url`: [[UrlValidator]]
+- `caseSensitive` whether the comparison is case sensitive. _(false)_
+- `captchaAction` the route of the controller action that renders the CAPTCHA image. _('site/captcha')_
+
+### `compare`: [[CompareValidator]]
+
+Compares the specified attribute value with another value and validates if they are equal.
+
+- `compareAttribute` the name of the attribute to be compared with. _(currentAttribute_repeat)_
+- `compareValue` the constant value to be compared with.
+- `operator` the operator for comparison. _('==')_
+
+### `date`: [[DateValidator]]
+
+Verifies if the attribute represents a date, time or datetime in a proper format.
+
+- `format` the date format that the value being validated should follow accodring to [[http://www.php.net/manual/en/datetime.createfromformat.php]]. _('Y-m-d')_
+- `timestampAttribute` the name of the attribute to receive the parsing result.
+
+### `default`: [[DefaultValueValidator]]
+
+Sets the attribute to be the specified default value.
+
+- `value` the default value to be set to the specified attributes.
+
+### `double`: [[NumberValidator]]
+
+Validates that the attribute value is a number.
+
+- `max` limit of the number. _(null)_
+- `min` lower limit of the number. _(null)_
+
+### `email`: [[EmailValidator]]
+
+Validates that the attribute value is a valid email address.
+
+- `allowName` whether to allow 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 validation process should take into account IDN (internationalized domain names). _(false)_
+
+### `exist`: [[ExistValidator]]
+
+Validates that the attribute value exists in a table.
+
+- `className` the ActiveRecord class name or alias of the class that should be used to look for the attribute value being
+  validated. _(ActiveRecord class of the attribute being validated)_
+- `attributeName` the ActiveRecord attribute name that should be used to look for the attribute value being validated.
+  _(name of the attribute being validated)_
+
+### `file`: [[FileValidator]]
+
+Verifies if an attribute is receiving a valid uploaded file.
+
+- `types` a list 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 required for the uploaded file.
+- `maxFiles` the maximum file count the given attribute can hold. _(1)_
+
+### `filter`: [[FilterValidator]]
+
+Converts the attribute value according to a filter.
+
+- `filter` PHP callback that defines a filter.
+
+Typically a callback is either the name of PHP function:
+
+```php
+array('password', 'filter', 'filter' => 'trim'),
+```
+
+Or an anonymous function:
+
+```php
+array('text', 'filter', 'filter' => function ($value) {
+	// here we are removing all swear words from text
+	return $newValue;
+}),
+```
+
+### `in`: [[RangeValidator]]
+
+Validates that the attribute value is among a list of values.
+
+- `range` list of valid values that the attribute value should be among.
+- `strict` whether the comparison is strict (both type and value must be the same). _(false)_
+- `not` whether to invert the validation logic. _(false)_
+
+### `integer`: [[NumberValidator]]
+
+Validates that the attribute value is an integer number.
+
+- `max` limit of the number. _(null)_
+- `min` lower limit of the number. _(null)_
+
+### `match`: [[RegularExpressionValidator]]
+
+Validates that the attribute value matches the specified pattern defined by regular expression.
+
+- `pattern` the regular expression to be matched with.
+- `not` whether to invert the validation logic. _(false)_
+
+### `required`: [[RequiredValidator]]
+
+Validates that the specified attribute does not have null or empty value.
+
+- `requiredValue` the desired value that the attribute must have. _(any)_
+- `strict` whether the comparison between the attribute value and [[requiredValue]] is strict. _(false)_
+
+### `safe`: [[SafeValidator]]
+
+Serves as a dummy validator whose main purpose is to mark the attributes to be safe for massive assignment.
+
+### `string`: [[StringValidator]]
+
+Validates that the attribute value is of certain length.
+
+- `length` specifies the length limit of the value to be validated. Can be `exactly X`, `array(min X)`, `array(min X, max Y)`.
+- `max`  maximum length. If not set, it means no maximum length limit.
+- `min` minimum length. If not set, it means no minimum length limit.
+- `encoding` the encoding of the string value to be validated. _([[\yii\base\Application::charset]])_
+
+### `unique`: [[UniqueValidator]]
+
+Validates that the attribute value is unique in the corresponding database table.
+
+- `className` the ActiveRecord class name or alias of the class that should be used to look for the attribute value being
+  validated. _(ActiveRecord class of the attribute being validated)_
+- `attributeName` the ActiveRecord attribute name that should be used to look for the attribute value being validated.
+  _(name of the attribute being validated)_
+
+### `url`: [[UrlValidator]]
+
+Validates that the attribute value is a valid http or https URL.
+
+- `validSchemes` list of URI schemes which should be considered valid. _array('http', 'https')_
+- `defaultScheme` the default URI scheme. If the input doesn't contain the scheme part, the default scheme will be
+  prepended to it. _(null)_
+- `enableIDN` whether validation process should take into account IDN (internationalized domain names). _(false)_
+
+Validating values out of model context
+--------------------------------------
+
+Sometimes you need to validate a value that is not bound to any model such as email. In Yii `Validator` class has
+`validateValue` method that can help you with it. Not all validator classes have it implemented but the ones that can
+operate without model do. In our case to validate an email we can do the following:
+
+```php
+$email = 'test@example.com';
+$validator = new yii\validators\EmailValidator();
+if ($validator->validateValue($email)) {
+	echo 'Email is valid.';
+} else {
+	echo 'Email is not valid.'
+}
+```
 
 TBD: refer to http://www.yiiframework.com/wiki/56/ for the format

framework/yii/validators/RegularExpressionValidator.php

@@ -30,7 +30,6 @@ class RegularExpressionValidator extends Validator
 	/**
 	 * @var boolean whether to invert the validation logic. Defaults to false. If set to true,
 	 * the regular expression defined via [[pattern]] should NOT match the attribute value.
-	 * @throws InvalidConfigException if the "pattern" is not a valid regular expression
 	 **/
 	public $not = false;
 
@@ -82,7 +81,6 @@ class RegularExpressionValidator extends Validator
 	 * @param \yii\base\View $view the view object that is going to be used to render views or view files
 	 * containing a model form with this validator applied.
 	 * @return string the client-side validation script.
-	 * @throws InvalidConfigException if the "pattern" is not a valid regular expression
 	 */
 	public function clientValidateAttribute($object, $attribute, $view)
 	{

framework/yii/validators/StringValidator.php

@@ -52,7 +52,7 @@ class StringValidator extends Validator
 	 */
 	public $tooLong;
 	/**
-	 * @var string user-defined error message used when the length of the value is not equal to [[is]].
+	 * @var string user-defined error message used when the length of the value is not equal to [[length]].
 	 */
 	public $notEqual;
 	/**