A validator examines its input with respect to some requirements and produces a boolean result - whether the input successfully validates against the requirements. If the input does not meet the requirements, a validator may additionally provide information about which requirement(s) the input does not meet.

For example, a web application might require that a username be between six and twelve characters in length and may only contain alphanumeric characters. A validator can be used for ensuring that usernames meet these requirements. If a chosen username does not meet one or both of the requirements, it would be useful to know which of the requirements the username fails to meet.

Having defined validation in this way provides the foundation for Zend_Validate_Interface, which defines two methods, isValid() and getMessages(). The isValid() method performs validation upon the provided value, returning true if and only if the value passes against the validation criteria.

If isValid() returns false, the getMessages() returns an array of messages explaining the reason(s) for validation failure.

The getErrors() method returns an array of shorter strings that identify the reason(s) for validation failure. These strings are meant to identify the errors. These strings are intended to be checked by your application code, not output to users. The error strings are class-dependent; each validate class defines its own set of error strings to identify the cause of the error. Each class also provides const definitions to match these error identifiers.

The following example illustrates validation of an e-mail address:

<?php
require_once 'Zend/Validate/EmailAddress.php';

$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    //
    // email appears to be valid
    //
} else {
    //
    // email is invalid; print the reasons
    //
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}

Validate classes provide a setMessage() method with which you can specify the format of a message returned by getMessages() in case of validation failure. The first argument of this method is a string containing the error message. You can include tokens in this string which will be substituted with data relevant to the validator. The token %value% is supported by all validators; this is substituted with the value you passed to isValid(). Other tokens may be supported on a case-by-case basis in each validate class. For example, %max% is a token supported by Zend_Validate_LessThan.

The second optional argument is a string that corresponds to the error identifiers returned by the getErrors() method. If you omit the second argument, setMessage() assumes the message you specify should be used for the first message declared in the validate class. Many validate classes only have one error message, so there is no need to specify distinctly which message you are specifying.

<?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    'The string \'%value%\' is too short; it must be at least %min% characters',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('word')) {
    $m = $validator->getMessages();
    echo $m[0];

    // echoes "The string 'word' is too short; it must be at least 8 characters"
}

You can set multiple messages using the setMessages() method. Its argument is an array containing key/message pairs.

<?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8, 12);

$validator->setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT => 'The string \'%value%\' is too short',
    Zend_Validate_StringLength::TOO_LONG  => 'The string \'%value%\' is too long'
));

If your application requires even greater flexibility with which it reports errors, you can access properties by the same name as the message tokens supported by a given validate class. The value property is always available in a validator; it is the value you specified as the argument of isValid(). Other properties may be supported on a case-by-case basis in each validate class.

<?php
require_once 'Zend/Validate/StringLength.php';

$validator = new Zend_Validate_StringLength(8, 12);

if (!validator->isValid('word')) {
    echo 'Word failed: '
        . $validator->value
        . '; its length is not between '
        . $validator->min
        . ' and '
        . $validator->max
        . "\n";
}

If it's inconvenient to load a given validate class and create an instance of the validator, you can use the static method Zend_Validate::is() as an alternative invocation style. The first argument of this method is a data input value, that you would pass to the isValid() method. The second argument is a string, which corresponds to the basename of the validate class, relative to the Zend_Validate namespace. The is() method automatically loads the class, creates an instance, and applies the isValid() method to the data input.

<?php
require_once 'Zend/Validate.php';

if (Zend_Validate::is($email, 'EmailAddress')) {
    //
    // Yes, email appears to be valid
    //
}

You can also pass an array of constructor arguments, if they are needed for the validator.

<?php
require_once 'Zend/Validate.php';

if (Zend_Validate::is($value, 'Between', array(1, 12))) {
    //
    // Yes, $value is between 1 and 12
    //
}

The is() returns a boolean value, the same as the isValid() method. When using the static is() method, errors and messages are not available.

The static usage can be convenient for invoking a validator ad hoc, but if you have the need to run a validator for multiple inputs, it's more efficient to use the non-static usage, creating an instance of the validator object and calling its isValid() method.

Also, the Zend_Filter_Input class allows you to instantiate and run multiple filter and validator classes on demand to process sets of input data. See ???.