General data checking is done by using `Validator` statically. Rules can be specified as a
parameter to the `rule()` method or accessed directly via the `is[RuleName]()` method name
// The following are equivalent:
Validator::rule('email', 'email@example.com'); // true
Validator::isEmail('foo-at-example.com'); // false
Data can also be validated against multiple rules, each having their own associated error
message. The rule structure is array-based and hierarchical based on rule names and
messages. Responses match the keys present in the `$data` parameter of `check()` up with an array
of rules which they violate.
$rules = array(
'title' => 'please enter a title',
'email' => array(
array('notEmpty', 'message' => 'email is empty'),
array('email', 'message' => 'email is not valid')
$data = array('email' => 'something');
$result = Validator::check($data, $rules);
$errors = array(
'title' => array('please enter a title'),
'email' => array('email is not valid')
See the `check()` method for more information an multi-value datasets. Custom validation rules
can also be added to `Validator` at runtime. These can either take the form of regular expression
strings or functions supplied to the `add()` method.
The `Validator` class includes a series of commonly-used rules by default, any of which may be
used in calls to `rule()` or `check()`, or called directly as a method. Additionally, many rules
have a variety of different _formats_ in which they may be specified. The following is the list
of the built-in rules, but keep in mind that none of them are hard-coded. Any rule may be
overridden by adding a new rule of the same name using the `add()` method.
- `notEmpty`: Checks that a string contains at least one non-whitespace character.
- `alphaNumeric`: Checks that a string contains only integer or letters.
- `lengthBetween`: Checks that a string length is within a specified range. Spaces are included
in the character count. The available options are `'min'` and `'max'`, which designate the
minimum and maximum length of the string.
- `blank`: Checks that a field is left blank **OR** only whitespace characters are present in its
value. Whitespace characters include spaces, tabs, carriage returns and newlines.
- `creditCard`: Checks that a value is a valid credit card number. This rule is divided into a
series of formats: `'amex'`, `'bankcard'`, `'diners'`, `'disc'`, `'electron'`, `'enroute'`,
`'jcb'`, `'maestro'`, `'mc'`, `'solo'`, `'switch'`, `'visa'`, `'voyager'`, `'fast'`. If no
format value is specified, the value defaults to `'any'`, which will validate the value if
_any_ of the available formats match. You can also use the `'fast'` format, which does a
high-speed, low-fidelity check to ensure that the value looks like a real credit card number.
This rule includes one option, `'deep'`, which (if set to `true`) validates the value using the
[Luhn algorithm](http://en.wikipedia.org/wiki/Luhn_algorithm) if the format validation is
successful. See the `luhn` validator below for more details.
- `date`: Checks that a value is a valid date that complies with one or more formats. Also
validates leap years. Possible formats are `'dmy'` (27-12-2010 or 27-12-10 separators can be a
space, period, dash, forward slash), `'mdy'` (12-27-2010 or 12-27-10 separators can be a space,
period, dash, forward slash), `'ymd'` (2010-12-27 or 10-12-27 separators can be a space,
period, dash, forward slash), `'dMy'` (27 December 2010 or 27 Dec 2010), `'Mdy'` (December 27,
2010 or Dec 27, 2010 comma is optional), `'My'` (December 2010 or Dec 2010) or `'my'` (12/2010
separators can be a space, period, dash, forward slash).
- `time`: Checks that a value is a valid time. Validates time as 24hr (HH:MM) or am/pm
([ H]H:MM[a|p]m). Does not allow / validate seconds.
- `boolean`: Checks that the value is or looks like a boolean value. The following types of
values are interpreted as boolean and will pass the check.
- boolean (`true`, `false`, `'true'`, `'false'`)
- boolean number (`1`, `0`, `'1'`, `'0'`)
- boolean text string (`'on'`, `'off'`, `'yes'`, `'no'`)
- `decimal`: Checks that a value is a valid decimal. Takes one option, `'precision'`, which is
an optional integer value defining the level of precision the decimal number must match.
- `email`: Checks that a value is (probably) a valid email address. The subject of validating
an actual email address is complicated and problematic. A regular expression that correctly
validates addresses against [RFC 5322](http://tools.ietf.org/html/rfc5322) would be several
pages long, with the drawback of being unable to keep up as new top-level domains are added.
Instead, this validator uses PHP's internal input filtering API to check the format, and
provides an option, `'deep'` ( _boolean_) which, if set to `true`, will validate that the email
address' domain contains a valid MX record. Keep in mind, this is just one of the many ways to
validate an email address in the overall context of an application. For other ideas or
examples, [ask Sean](http://seancoates.com/).
- `ip`: Validates a string as a valid IPv4 or IPv6 address.
- `money`: Checks that a value is a valid monetary amount. This rule has two formats, `'right'`
and `'left'`, which indicates which side the monetary symbol (i.e. $) appears on.
- `numeric`: Checks that a value is numeric.
- `phone`: Check that a value is a valid phone number, non-locale-specific phone number.
- `postalCode`: Checks that a given value is a valid US postal code.
- `inRange`: Checks that a numeric value is within a specified range. This value has two options,
`'upper'` and `'lower'`, which specify the boundary of the value.
- `url`: Checks that a value is a valid URL according to
[RFC 2395](http://www.faqs.org/rfcs/rfc2396.html). Uses PHP's filter API, and accepts any
options accepted for
[the validation URL filter](http://www.php.net/manual/en/filter.filters.validate.php).
- `luhn`: Checks that a value is a valid credit card number according to the
[Luhn algorithm](http://en.wikipedia.org/wiki/Luhn_algorithm). (See also: the `creditCard`
- `inList`: Checks that a value is in a pre-defined list of values. This validator accepts one
option, `'list'`, which is an array containing acceptable values.
- `regex`: Checks that a value appears to be a valid regular expression, possibly
containing PCRE-compatible options flags.
- `uuid`: Checks that a value is a valid UUID.
### UTF-8 encoded input strings
All rules operating on strings have been created with the possibility of
UTF-8 encoded input in mind. A default PHP binary and an enabled Lithium
g11n bootstrap will make these rules work correctly in any case. Should you
ever experience odd behavior following paragraph with implementation
details might help you to track to the cause.
The rules `alphaNumeric` and `money` rely on additional functionality of
PCRE to validate UTF-8 encoded strings. As no PCRE feature detection is
done, having this feature enabled in PCRE isn't optional. Please ensure
you've got PCRE compiled with UTF-8 support.