Skip to content
Browse files

Updating documentation for `\util\Validator`, adding tests to prove f…

…unctionality in ticket #44, fixing doc formatting in `\action\Controller`.
  • Loading branch information...
1 parent 593b41d commit 50899556d6978e3aad799871925e097a0385bdb9 @nateabele nateabele committed
View
2 libraries/lithium/action/Controller.php
@@ -201,7 +201,7 @@ public function set($data = array()) {
* - `'data'`: An associative array of variables to be assigned to the template. These
* are merged on top of any variables set in `Controller::set()`.
* - `'head'`: If true, only renders the headers of the response, not the body. Defaults
- * to false.
+ * to `false`.
* - `'template'`: The name of a template, which usually matches the name of the action.
* By default, this template is looked for in the views directory of the current
* controller, i.e. given a `PostsController` object, if template is set to `'view'`,
View
18 libraries/lithium/tests/cases/util/ValidatorTest.php
@@ -961,6 +961,24 @@ public function testIsInRange() {
$this->assertTrue(Validator::isInRange(0));
}
+
+ public function testValidationWithContextData() {
+ Validator::add('someModelRule', function($value, $format, $options) {
+ return $value == 'Title' && $options['values']['body'] == 'Body';
+ });
+
+ $result = Validator::check(
+ array('title' => 'Title', 'body' => 'Body'),
+ array('title' => array('someModelRule'))
+ );
+ $this->assertIdentical(array(), $result);
+
+ $result = Validator::check(
+ array('title' => 'Title', 'body' => 'Not Body'),
+ array('title' => array('someModelRule'))
+ );
+ $this->assertIdentical(array('title' => array(0)), $result);
+ }
}
?>
View
44 libraries/lithium/util/Validator.php
@@ -294,7 +294,46 @@ public static function __callStatic($method, $args = array()) {
* @param array $values An array of key/value pairs, where the values are to be checked.
* @param array $rules An array of rules to check the values in `$values` against. Each key in
* `$rules` should match a key contained in `$values`, and each value should be a
- * validation rule in one of the allowable formats.
+ * validation rule in one of the allowable formats. For example, if you are
+ * validating a data set containing a `'title'` key, possible values for
+ * `$rules` would be as follows:
+ * - `array('title' => 'You must include a title')`: This is the simplest form of
+ * validation rule, in which the value is simply a message to display if the rule
+ * fails. Using this format, all other validation settings inherit from the
+ * defaults, including the validation rule itself, which only checks to see that
+ * the corresponding key in `$values` is present and contains a value that is not
+ * empty. _Please note when globalizing validation messages:_ When specifying
+ * messages, it may be preferable to use a code string (i.e. `'ERR_NO_TITLE'`)
+ * instead of the full text of the validation error. These code strings may then
+ * be translated by the appropriate tools in the templating layer.
+ * - `array('title' => array('alphaNumeric', 'message' => 'Invalid title'))`: In
+ * the second format, the validation rule and associated configuration are
+ * specified as an array, where the rule to use is the first value in the array
+ * (no key), and additional settings are specified as other keys in the array.
+ * Please see the list below for more information on allowed keys.
+ * - The final format allows you to apply multiple validation rules to a single
+ * value, and it is specified as follows:
+ *
+ * `array('title' => array(
+ * array('notEmpty', 'message' => 'You must include a title'),
+ * array('alphaNumeric', 'message' => 'Your title must be alphanumeric')
+ * ));`
+ *
+ * Each rule defined as an array can contain any of the following settings (in addition to the
+ * first value, which represents the rule to be used):
+ * - `'message'` _string_: The error message to be returned if the validation rule fails. See
+ * the note above regarding globalization of error messages.
+ * - `'required`' _boolean_: Represents whether the value is required to be present in
+ * `$values`. If `'required'` is set to `false`, the validation rule will be skipped if the
+ * corresponding key is not present. Defaults to `true`.
+ * - `'skipEmpty'` _boolean_: Similar to `'required'`, this setting (if `true`) will cause the
+ * validation rule to be skipped if the corresponding value is empty (an empty string or
+ * `null`). Defaults to `false`.
+ * - `'format'` _string_: If the validation rule has multiple format definitions (see the
+ * `add()` or `__init()` methods), the name of the format to be used can be specified here.
+ * Additionally, two special values can be used: either `'any'`, which means that all formats
+ * will be checked and the rule will pass if any format passes, or `'all'`, which requires
+ * all formats to pass in order for the rule check to succeed.
* @return array Returns an array containing all validation failures for data in `$values`,
* where each key matches a key in `$values`, and each value is an array of that
* element's validation errors.
@@ -305,8 +344,7 @@ public static function check(array $values, array $rules, array $options = array
'message' => null,
'required' => true,
'skipEmpty' => false,
- 'format' => 'any',
- 'last' => false
+ 'format' => 'any'
);
$errors = array();

0 comments on commit 5089955

Please sign in to comment.
Something went wrong with that request. Please try again.