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
convention:
{{{
use lithium\util\Validator;
The following are equivalent:
Validator::rule('email', 'foo@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.
{{{ embed:lithium\tests\cases\util\ValidatorTest::testCheckMultipleHasFirstError(1-15) }}}
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.
### Rules
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 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 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.
- 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. Uses PHP's filter API, and accepts any
options accepted for
the validation URL filter.
- luhn: Checks that a value is a valid credit card number according to the
Luhn algorithm. (See also: the creditCard
validator).
- 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.