9.6. Validator Usage Examples

Next, we will consider the usage of the most important standard validators. These describe the methods (and options) a validator has, and provide a code example showing how to instantiate and apply the validator to input data.

9.6.1. Validators for Checking Value Conformance to Certain Format

In this section, we will consider usage examples of the validators from the group of validators designed for checking if input value conforms to certain format.

9.6.1.1. Ip Validator

The Ip validator class is designed to check if the input value is a valid IP address. If the input value is an IPv4 ³² address, IPv6 ³³ address, IPvFuture ³⁴ address, or IPv6 literal ³⁵ address, the validator returns boolean true; otherwise it returns false. On failure, error messages can be extracted with the validator's getMessages() method.

³²⁾ An Internet Protocol version 4 (IPv4) address typically consists of four octets of the address expressed separated by periods, like "192.168.56.101".

³³⁾ An Internet Protocol version 6 (IPv6) address typically consists of eight groups of four hexadecimal digits separated by colons, such as "2001:0db8:85a3:0000:0000:8a2e:0370:7334".

³⁴⁾ IPvFuture is loosely defined in the Section 3.2.2 of RFC 3986.

³⁵⁾ A literal IPv6 address is a modification of a usual IPv6 address for using inside of a URL. (The problem with original IPv6 addresses is that the ":" and "." characters are delimiters in URLs.)

Public methods provided by the Ip validator are listed in table 9.3:

The setOptions() method provides an ability to set allowed types of IP addresses:

• allowipv4 to allow IPv4 addresses;
• allowipv6 to allow IPv6 addresses;
• allowipvfuture to allow IPvFuture addresses;
• allowliteral to allow IPv6 literal addresses.

By default all the above are allowed, except the IPv6 literal address.

Below, a code example demonstrating the usage of the Ip validator is provided.

<?php
use Zend\Validator\Ip;

// Create Ip validator.
$validator = new Ip();

// Configure the validator.
$validator->setOptions([
    'allowipv4'      => true,  // Allow IPv4 addresses.
    'allowipv6'      => true,  // Allow IPv6 addresses.
    'allowipvfuture' => false, // Allow IPvFuture addresses.
    'allowliteral'   => true,  // Allow IP addresses in literal format.
  ]);

// Check if input value is a valid IP address (IPv4).
$isValid = $validator->isValid('192.168.56.101'); // Returns true

// Check if input value is a valid IP address (IPv6).
$isValid2 = $validator->isValid(
       '2001:0db8:85a3:0000:0000:8a2e:0370:7334'); // Returns true

// Pass an invalid string (not containing an IP address).       
$isValid3 = $validator->isValid('abc'); // Returns false

9.6.1.2. Hostname Validator

The Hostname validator is designed to check if a given value is a host name belonging to set of allowed host name types. The types are:

• a DNS Hostname (e.g. "example.com");
• an IP address (e.g. "192.168.56.101");
• a local host name (e.g. "localhost").

The public methods provided by the validator are listed in table 9.4:

You can set which host name types are allowed with the setAllow() method. It accepts a combination of the following constants:

• ALLOW_DNS Allows Internet domain names (e.g., example.com);
• ALLOW_IP Allows IP addresses;
• ALLOW_LOCAL Allows local network names (e.g., localhost, www.localdomain);
• ALLOW_URI Allows URI host names.
• ALLOW_ALL Allows all types of host names.

By default, only Internet domain names are allowed.

The host name check consists of several stages, some of which may be omitted based on validator options:

1. If the input value looks like an IP address, it is checked with the internal IP address validator. You can override which IP address validator to use for this by the setIpValidator() method.

2. The host name is separated into domain parts (separated with dot "." character).

3. The top-level domain is checked against the white list of available TLDs. (You can disable this check with the useTldCheck() method.)

4. Each domain part is checked based on the rules for acceptable domain names. If a domain name is an IDN ³⁶, it is checked against the rules for valid IDNs. (You can disable IDN check with useIdnCheck() method.)

³⁶⁾ An internationalized domain name (IDN) is an Internet domain name that contains at least one label that is displayed, in whole or in part, in a language-specific script or alphabet, like Arabic, Chinese or Russian.

Below, a code example demonstrating the usage of the Hostname validator is provided.

<?php
use Zend\Validator\Hostname;

// Create the Hostname validator.
$validator = new Hostname();

// Configure the validator.
$validator->setAllow(Hostname::ALLOW_DNS|Hostname::ALLOW_IP);

// Check a host name.
$isValid = $validator->isValid('site1.example.com'); 
// Returns true.
$isValid2 = $validator->isValid('abc'); 
// Returns false (not a valid host name).

9.6.1.3. Uri Validator

The Uri validator is designed to check whether the input value is a Uniform Resource Identifier (URI) ³⁷. On failure, error messages can be extracted with the validator's getMessages() method.

Don't be confused with the term URI. In most cases, you may think of URI as of a usual URL.

³⁷⁾ A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. An Uniform Resource Locator (URL) is a type of URI. But, that doesn't mean all URIs are URLs.

The public methods provided by the Uri validator are listed in table 9.5:

Internally, the Uri validator uses so called URI handler object, which is responsible for parsing an URI string. By default, Zend\Uri\Uri class is used as the URI handler. (You can set your custom URI handler with the setUriHandler() method, if you wish.)

An URI can be absolute or relative. For example, an absolute URI is "http://example.com/blog/2014/02/02/edit", while a relative URI is "2014/02/02/edit". You can specify whether the validator should consider absolute and/or relative URIs acceptable. For that, you use the setAllowAbsolute() and setAllowRelative() methods, respectively. By default, both are treated as acceptable URI types.

Below, a code example demonstrating the usage of the Uri validator is provided.

<?php
use Zend\Validator\Uri;

// Create the Uri validator.
$validator = new Uri();

// Configure the validator.
$validator->setAllowAbsolute(true);
$validator->setAllowRelative(true);

// Check an URI.
$isValid = $validator->isValid('http://site1.example.com/application/index/index'); 
// Returns true.
$isValid2 = $validator->isValid('index/index'); 
// Returns true.

9.6.1.4. Date Validator

The Date validator is intended for checking whether the input data is a date in a given format. On failure, error messages can be extracted with the validator's getMessages() method.

Public methods provided by the Date validator are listed in table 9.6:

To set the expected date format, you can use the setFormat() method.

Internally, the DateTimeFormatter filter uses the DateTime class from the PHP standard library for converting and formatting dates. For available date formats, please refer to the PHP documentation for the DateTime class.

Below, a code example demonstrating the usage of the Date validator is provided.

<?php
use Zend\Validator\Date;

// Create validator instance.
$validator = new Date();

// Configure validator.
$validator->setFormat('Y-m-d');

// Check if the input value is a date having expected format.
$isValid = $validator->isValid('2014-04-04'); // Returns true.
$isValid2 = $validator->isValid('April 04, 2014'); // Returns false (format is unexpected).

9.6.1.5. Regex Validator

This validator allows you to validate if a given string conforms some regular expression. It returns true if the string matches the regular expression, otherwise it returns false. On failure, error messages can be extracted with the validator's getMessages() method.

The public methods provided by the Regex validator are listed in table 9.7:

The setPattern() method allows to set the regular expression to match against.

For regular expressions syntax and examples, it is recommended that your refer to the PCRE Patterns section of the PHP documentation.

Below, a code example demonstrating the usage of the Regex validator is provided. It uses the regular expression to check if the input string is a valid IPv4 address (such address typically consists of four groups of digits separated with dots).

<?php
use Zend\Validator\Regex;

// Create Regex validator.
$validator = new Regex();

// Set regular expression to check for an IP address.
$validator->setPattern('\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b');

// Check for regular expression match.
$isValid = $validator->isValid("127.0.0.1"); // returns true.
$isValid2 = $validator->isValid("123"); // returns false.

9.6.2. Validators for Checking if a Numerical Value Lies in a Given Range

In this section, we will consider usage examples of the validators from the group of validators designed for checking if input value lies in a given range.

9.6.2.1. NotEmpty Validator

The NotEmpty validator allows to check if input value is not empty. This is often useful when working with form elements or other user input, where you can use it to ensure required elements have values associated with them.

The public methods provided by the NotEmpty validator are listed in table 9.8:

The setType() method specifies which variable types to consider as an empty value. This method accepts the single argument $type which can be either an OR combination of the constants listed in table 9.9, or an array containing the literal equivalents of those constants.

Below, a code example demonstrating the usage of the NotEmpty validator is provided.

<?php
use Zend\Validator\NotEmpty;

// Create validator instance.
$validator = new NotEmpty();

// Configure validator.
$validator->setType(NotEmpty::ALL);

// Check if input value not empty.
$isValid1 = $validator->isValid('some string'); // returns true
$isValid2 = $validator->isValid(''); // returns false 
$isValid3 = $validator->isValid(0); // returns false

9.6.2.2. Between Validator

The Between validator checks whether a number lies in a certain range (min, max), either inclusively (by default) or exclusively.

The public methods provided by the Between validator are listed in table 9.10:

The range can be set with the setMin() and setMax() methods.

By default, the validator performs inclusive comparisons (to check if the value belongs to the given range, it compares if the value is greater or equal to its lower bound, and if the value is lower or equal to its upper bound). You can change this with the setInclusive() method. It tells the validator whether to perform inclusive comparisons (pass true as the argument) or exclusive comparisons (pass false as the argument).

Below, a code example demonstrating the usage of the Between validator is provided.

<?php
use Zend\Validator\Between;

// Create validator instance.
$validator = new Between();

// Configure validator.
$validator->setMin(1);
$validator->setMax(10);
$validator->setInclusive(true);

$isValid1 = $validator->isValid(5); // returns true.
$isValid2 = $validator->isValid(10); // returns true.
$isValid3 = $validator->isValid(0); // returns false (value is too small).
$isValid4 = $validator->isValid(15); // returns false (value is too big).

9.6.2.3. InArray Validator

The InArray validator checks whether the input value belongs to the given array of values. The public methods provided by the InArray validator are listed in table 9.11:

The setHaystack() method allows to set the array of allowed values. The isValid() method will search through this array for the presence of the input $value.

If the array contains nested values and you want to search among them recursively, then use setRecursive() method. This method takes the single boolean flag. If the flag is true, than the search will be performed recursively; otherwise the nested levels will be ignored.

The setStrict() method provides an ability to tell the validator how to compare the input value and the values in array. This may be a combination of the following constants:

• COMPARE_NOT_STRICT Do not perform strict check of variable type.
• COMPARE_NOT_STRICT_AND_PREVENT_STR_TO_INT_VULNERABILITY Do not perform strict check of variable type, but prevent false positive comparisons of string to integer (e.g. "asdf" == 0). This is the default option.
• COMPARE_STRICT Check both variable type and value.

Below, a code example demonstrating the usage of the InArray validator is provided.

<?php
use Zend\Validator\InArray;

// Create validator instance.
$validator = new InArray();

// Configure validator.
$validator->setHaystack([1, 3, 5]);

// Perform validation.
$isValid1 = $validator->isValid(1); // returns true.
$isValid2 = $validator->isValid(2); // returns false.

9.6.2.4. StringLength Validator

The StringLength validator checks whether the input string length belongs to the given range, inclusively. It returns true if and only if the string length of value is at least the min option and no greater than the max option (when the max option is not null).

The public methods provided by the StringLength validator are listed in table 9.12:

By default, the StringLength validator considers any string length as valid. Use the setMin() and/or setMax() methods to set lower and upper limits for the allowable string length. There are three possible ways you can do that:

• Use only the setMin() method to allow strings with a lower-bound minimum length, but unbound upper length;
• Use only the setMax() method to allow strings with zero minimum length and an upper-bound maximum length;
• Use both the setMin() and setMax() methods to allow strings with a length laying between the lower and upper bounds.

By default, the PHP engine uses the UTF-8 encoding for strings. If your input string uses a different encoding, you should specify it encoding with the setEncoding() validator's method.

Below, a code example demonstrating the usage of the StringLength validator is provided.

<?php
use Zend\Validator\StringLength;

// Create validator instance.
$validator = new StringLength();

// Configure the validator.
$validator->setMin(1);
$validator->setMax(10);

$isValid1 = $validator->isValid("string"); // returns true.
$isValid2 = $validator->isValid(""); // returns false (value is too short).
$isValid3 = $validator->isValid("a very long string"); // returns false (value is too long).

9.6.3. Organizing Validators in a Chain

Validators can be organized in a sequence. This is accomplished by the ValidatorChain class. When such a compound validator is run, the input value is passed to all validators in turn. The ValidatorChain validator's isValid() method returns true if all validators in the chain return true; otherwise it returns false.

The ValidatorChain class is internally used by the InputFilter container class for storing the sequence of validators attached to a form model's field.

Public methods provided by the ValidatorChain class are presented in table 9.13:

An example validator chain is shown in figure 9.2. It consists of the NotEmpty validator followed by the StringLength validator, which in turn is followed by the Date validator. When this chain is executed, first, the NotEmpty validator is run checking that the value is a non-empty value, then the StringLength validator is run checking that the length of the input string belongs to range (1, 16), inclusively, and finally, the Date validator is run checking that the input value is a date in format "YYYY-MM-DD".

Figure 9.2. Validator chain

To construct the filter chain like in figure 9.2, we can use the following code:

<?php
// Instantiate the validator chain.
$validator = new \Zend\Validator\ValidatorChain();

// Insert validators into validator chain.
$validator->attachByName('NotEmpty');
$validator->attachByName('StringLength', ['min'=>1, 'max'=>16]);
$validator->attachByName('Date', ['format'=>'Y-m-d']);

// Execute all validators in the chain.
$isValid = $validator->isValid('2014-04-04'); // Returns true.

9.6.4. Custom Validation with the Callback Validator

The Callback validator can be a wrapper for your custom validation algorithm. For example, this may be useful when a standard validator is not suitable, and you need to apply your own checking algorithm to the data. The public methods provided by the Callback validator are listed in table 9.14.

As you can see from the table, the Callback validator provides the setCallback() and setCallbackOptions() methods that can be used to set the callback function or class method and (optionally) pass it one or several parameters.

9.6.4.1. Example

To demonstrate the usage of the Callback validator, let's add the phone number validator to our ContactForm form model class. The validator would check a telephone number entered by site visitor.

The validator needs to be able to check for two common phone number formats:

• international format looking like "1 (234) 567-8901";
• and local format, which looks like "567-8901".

Because ZF3 does not provide a standard validator for accomplishing such phone filtering operation, we will use the Callback wrapper validator. To do that, we will make the following changes to the code of our ContactForm class:

<?php
// ...
class ContactForm extends Form
{    
  // ..
  protected function addElements() {
    // ...
	
    // Add "phone" field
    $this->add([
        'type'  => 'text',
        'name' => 'phone',
        'attributes' => [                
          'id' => 'phone'
        ],
        'options' => [
          'label' => 'Your Phone',
        ],
      ]);
  }
    
  private function addInputFilter() 
  {
    // ...
        
    $inputFilter->add([
            'name'     => 'phone',
            'required' => true,                
            'validators' => [
                [
                  'name' => 'Callback',
                  'options' => [
                     'callback' => [$this, 'validatePhone'],
                     'callbackOptions' => [
                     'format' => 'intl'
                  ]
                ]                        
              ]                    
            ]
        );
  }
        
  // Custom validator for a phone number.
  public function validatePhone($value, $context, $format) 
  {
    // Determine the correct length and pattern of the phone number,
    // depending on the format.
    if($format == 'intl') {
      $correctLength = 16;
      $pattern = '/^\d\ (\d{3}\) \d{3}-\d{4}$/';
    } else { // 'local'
      $correctLength = 8;
      $pattern = '/^\d{3}-\d{4}$/';
    }
                
    // Check phone number length.
    if(strlen($value)!=$correctLength)
      return false;

    // Check if the value matches the pattern.
    $matchCount = preg_match($pattern, $value);
        
    return ($matchCount!=0)?true:false;
  }
}

In the code above, we create the phone field in our ContactForm (if you already have such field, just ignore this).

In lines 26-40, we add the Callback validator to the input filter's validator chain for the "phone" field.

In lines 44-64, we have the validatePhone() callback method. The method accepts three arguments: the $value parameter is the phone number to validate, the $context parameter receives the values of every field of the form (it may be needed for some validators to refer to the values of other form fields, too); and the $format parameter is the expected format of the phone number ("intl" or "local").

Inside of the callback method, we do the following:

1. Calculate the correct length of the phone, check whether the length is correct for the selected phone number format.
2. Match the phone number against the regular expression pattern for the selected phone format.