Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at:
Writing Validators - Zend_Validate
Zend_Validate supplies a set of commonly needed validators, but inevitably, developers will wish to write custom validators for their particular needs. The task of writing a custom validator is described in this section.
Zend_Validate_Interface defines two methods, isValid() and getMessages(), that may be implemented by user classes in order to create custom validation objects. An object that implements Zend_Validate_Interface interface may be added to a validator chain with Zend_Validate::addValidator(). Such objects may also be used with Zend_Filter_Input.
As you may already have inferred from the above description of Zend_Validate_Interface, validation classes provided with Zend Framework return a boolean value for whether or not a value validates successfully. They also provide information about why a value failed validation. The availability of the reasons for validation failures may be valuable to an application for various purposes, such as providing statistics for usability analysis.
Basic validation failure message functionality is implemented in Zend_Validate_Abstract. To include this functionality when creating a validation class, simply extend Zend_Validate_Abstract. In the extending class you would implement the isValid() method logic and define the message variables and message templates that correspond to the types of validation failures that can occur. If a value fails your validation tests, then isValid() should return FALSE. If the value passes your validation tests, then isValid() should return TRUE.
In general, the isValid() method should not throw any exceptions, except where it is impossible to determine whether or not the input value is valid. A few examples of reasonable cases for throwing an exception might be if a file cannot be opened, an LDAP server could not be contacted, or a database connection is unavailable, where such a thing may be required for validation success or failure to be determined.
Example #1 Creating a Simple Validation Class
The following example demonstrates how a very simple custom validator might be written. In this case the validation rules are simply that the input value must be a floating point value.
The class defines a template for its single validation failure message, which includes the built-in magic parameter, %value%. The call to _setValue() prepares the object to insert the tested value into the failure message automatically, should the value fail validation. The call to _error() tracks a reason for validation failure.
Example #2 Writing a Validation Class having Dependent Conditions
The following example demonstrates a more complex set of validation rules, where it is required that the input value be numeric and within the range of minimum and maximum boundary values. An input value would fail validation for exactly one of the following reasons:
The input value is not numeric.
The input value is less than the minimum allowed value.
The input value is more than the maximum allowed value.
These validation failure reasons are then translated to definitions in the class:
The public properties $minimum and $maximum have been established to provide the minimum and maximum boundaries, respectively, for a value to successfully validate. The class also defines two message variables that correspond to the public properties and allow min and max to be used in message templates as magic parameters, just as with value.
Note that if any one of the validation checks in isValid() fails, an appropriate failure message is prepared, and the method immediately returns FALSE. These validation rules are therefore sequentially dependent. That is, if one test should fail, there is no need to test any subsequent validation rules. This need not be the case, however. The following example illustrates how to write a class having independent validation rules, where the validation object may return multiple reasons why a particular validation attempt failed.
Example #3 Validation with Independent Conditions, Multiple Reasons for Failure
Consider writing a validation class for password strength enforcement - when a user is required to choose a password that meets certain criteria for helping secure user accounts. Let us assume that the password security criteria enforce that the password:
is at least 8 characters in length,
contains at least one uppercase letter,
contains at least one lowercase letter,
and contains at least one digit character.
The following class implements these validation criteria:
Note that the four criteria tests in isValid() do not immediately return FALSE. This allows the validation class to provide all of the reasons that the input password failed to meet the validation requirements. if, for example, a user were to input the string "#$%" as a password, isValid() would cause all four validation failure messages to be returned by a subsequent call to getMessages().