9.6. Ejemplos de uso de validadores

Ahora consideraremos el uso de los más importantes validadores estándares. Describiremos los métodos y las opciones que tiene el validador y daremos un ejemplo que muestra como instanciar y aplicar el validador a los datos de entrada.

9.6.1. Validadores para revisar la conformidad de un valor a un formato determinado

En esta sección, consideraremos ejemplos de uso de los validadores del grupo de validadores diseñados para revisar si los valores de entrada se ajustan a un formato determinado.

9.6.1.1. Validador Ip

La clase de validación Ip está diseñada para revisar si el valor de entrada es una dirección IP valida. Si el valor de entrada es una dirección IPv4 ³², IPv6 ³³, IPvFuture ³⁴ o una IPv6 literal ³⁵; el validador regresara un booleano true, de lo contrario regresa false. En caso de fallo los mensajes de error se pueden extraer con el método getMessages() del validador.

Los métodos públicos provistos por el validador Ip se listan en la tabla 9.3:

El método setOptions() permite indicar los tipos de dirección IP permitidos:

• allowipv4 para permitir direcciones IPv4.
• allowipv6 para permitir direcciones IPv6.
• allowipvfuture para permitir direcciones IPvFuture.
• allowliteral para permitir direcciones IPv6 literal.

Por defecto todas las direcciones que se muestran arriba son permitidas con la excepción de la dirección IPv6 literal.

Abajo tenemos un código de ejemplo que demuestra el uso del validador Ip.

<?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. Validador Hostname

El validador Hostname está diseñado para revisar si el valor dado es un nombre de servidor que pertenece al conjunto de tipos de nombres de servidor permitidos. Los tipos son:

• Un nombre de servidor DNS (ejemplo, «example.com»);
• Una dirección IP (ejemplo, «192.168.56.101»);
• Un nombre de servidor local (ejemplo, «localhost»).

Los métodos públicos provistos por el validador se listan en la tabla 9.4:

Podemos indicar los nombres de los tipos de servidor permitidos con el método setAllow(). Este método acepta la combinación de las siguientes constantes:

• ALLOW_DNS permite nombres de dominio de Internet (ejemplo, example.com).
• ALLOW_IP permite direcciones IP.
• ALLOW_LOCAL permite nombres locales de red (ejemplo, localhost, www.localdomain);
• ALLOW_URI permite nombre URI de servidor.
• ALLOW_ALL permite todos los tipos de nombre de servidor.

Por defecto, solo se permiten los nombre de dominio de Internet.

La revisión del nombre de servidor consiste de varias etapas, algunas se pueden omitir dependiendo de las opciones del validador:

1. Si el valor de entrada se parece a una dirección IP, esta se revisa con el validador de direcciones IP interno. Podemos sobrescribir el validador de direcciones IP con el método setIpValidator().

2. El nombre del servidor se separa dejando la parte del dominio (con el separador «.»).

3. El dominio de primer nivel se revisa contra la lista blanca con los TLDs permitidos. (Podemos desactivar esta revisión con el método useTldCheck()).

4. La parte de dominio se revisa en base a las reglas de nombres de dominio aceptables. Si un nombre de dominio es un IDN ³⁶ se revisa contra las reglas para validar IDNs. (Podemos desactivar la revisión IDN con el método useIdnCheck()).

Abajo, mostramos un código de ejemplo que demuestra el uso del validador Hostname.

<?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. El validador Uri

El validador Uri está diseñado para revisar si el valor de entrada es un Identificador de Recursos Uniforme (URI) ³⁷. En caso de falla los mensajes de error se pueden recuperar con el método del validador getMessages().

No nos confundamos con el termino URI. En la mayoría de los casos podemos pensar a la URI como un URL usual.

Los métodos públicos que provee el validador Uri se listan en la tabla 9.5:

Internamente, el validador Uri usa el gestor de objetos URI (URI handler object) que es responsable de analizar la cadena de caracteres de la URI. Por defecto, la clase Zend\Uri\Uri se usa como gestor de URI. (Si queremos, podemos colocar nuestro gestor de URI personalizado con el método setUriHandler()).

Una URI puede ser absoluta o relativa. Por ejemplo, una URI absoluta es «http://example.com/blog/2014/02/02/edit», mientras que una relativa es «2014/02/02/edit». Podemos especificar si el validador considera aceptables a las URIs relativas, a las absolutas o ambas. Para esto, usamos los métodos setAllowAbsolute() and setAllowRelative(), respectivamente. Por defecto, ambas son tratadas como tipos de URI aceptables.

Abajo, un código de ejemplo muestra el uso del validador Uri.

<?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. El validador Date

El validador Date está pensado para revisar si el dato de entrada es una fecha en un formato dado. En caso de falla, los mensajes de error se pueden extraer con el método del validador getMessages().

Los métodos públicos que provee el validador Date se listan en la tabla 9.6:

Para colocar el formato de la fecha que se espera podemos usar el método setFormat().

Internamente, el filtro DateTimeFormatter usa la clase DateTime de la biblioteca estándar de PHP para convertir y formatear las fechas. Los formatos de fecha disponibles los podemos conseguir en la documentación de PHP de la clase DateTime.

Abajo, un código de ejemplo demuestra el uso del validador Date.

<?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. El validador Regex

Este validador nos permite validar si una cadena de caracteres dada cumple alguna expresión regular. Regresa true si la cadena de caracteres coincide con la expresión regular, de lo contrario regresa false. En caso de fallo, los mensajes de error se pueden extraer con el método getMessages() del validador.

Los métodos públicos que provee el validador Regex se listan en la tabla 9.7:

El método setPattern() permite colocar la expresión regular sobre la que se hace la comparación.

Para conocer la sintaxis y ver ejemplos de las expresiones regulares recomendamos revisar la sección Patrones PCRE de la documentación de PHP.

Abajo, con un código de ejemplo mostramos el uso del validador Regex. En el ejemplo usamos una expresión regular para revisar si la cadena de caracteres de entrada es una dirección IPv4 valida (una dirección consiste típicamente consiste en cuatro grupos de dígitos separados por puntos).

<?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. Validadores para revisar si un valor numérico está en un rango dado

En esta sección consideraremos ejemplos de uso de validadores del grupo de validadores diseñados para revisar si los datos de entrada están en un rango dado.

9.6.2.1. Validador NotEmpty

El validador NotEmpty permite revisar si el dato de entrada no está vacío. Este validador es útil cuando se trabaja con elementos de formulario u otras entradas de usuario, en donde podemos usarlo para asegurar que los elementos obligatorios tienen valores asociados.

Los métodos públicos que provee el validador NotEmpty se listan en la tabla 9.8:

El método setType() específica que tipos de variables se consideran valores vacíos. Este método acepta un solo argumento $type que puede ser o una combinación OR de las constantes listadas en la tabla 9.9, o un arreglo que contenga los equivalentes literales de estas constantes.

Abajo, mostramos un código de ejemplo que demuestra el uso del validador NotEmpty.

<?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. Validador Between

El validador Between revisa si un número está en un determinado rango (min, max), incluyéndolos (por defecto) o excluyéndolos.

Los métodos públicos que provee el validador @Between se listan en la tabla 9.10:

El rango se puede colocar con los métodos setMin() y setMax().

Por defecto el validador ejecuta una comparación inclusiva (para revisar si el valor pertenece al rango dado, se compara si el valor es mayor o igual a su límite inferior y si el valor es menor o igual a su límite superior). Se puede cambiar este comportamiento con el método setInclusive(). Este le dice al validador si ejecuta una comparación inclusiva (pasando true como argumento) o una comparación exclusiva (pasando false como argumento).

Abajo, se muestra un ejemplo del uso del validador Between.

<?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. Validador InArray

El validador InArray revisa si el valor de entrada pertenece a un arreglo dado. Los métodos públicos provistos por el validador InArray se listan en la tabla 9.11:

El método setHaystack() permite colocar el arreglo de valores permitidos. El método isValid() buscará en el arreglo la presencia de $value.

Si el arreglo contiene valores anidados y queremos buscar en él recursivamente, entonces usamos el método setRecursive(). Este método toma una bandera booleana. Si la bandera es true, entonces la búsqueda sera ejecutada recursivamente, de lo contrario los niveles anidados serán ignorados.

El método setStrict() provee la capacidad de decirle al validador como comparar el valor de entrada y los valores en el arreglo. Este puede ser una combinación de las siguientes constantes:

• COMPARE_NOT_STRICT no ejecutar una revisión estricta del tipo de variable.
• COMPARE_NOT_STRICT_AND_PREVENT_STR_TO_INT_VULNERABILITY no ejecutar una revisión estricta del tipo de variable, pero previene un falso positivo producto de la comparación de una cadena de caracteres con un entero (por ejemplo, "asdf" == 0). Esta es la opción por defecto.
• COMPARE_STRICT comparar tanto el tipo de variable como su valor.

Abajo, demostramos con un ejemplo el uso del validador InArray.

<?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. Validador StringLength

El validador StringLength revisa si la longitud de la cadena de caracteres de entrada pertenece a un rango dado, incluyendo los extremos. Regresa true si y solo si la longitud de la cadena de caracteres tiene el valor min y no es mayor que la opción max (cuando la opción max no es nula).

Los métodos públicos que provee el validador StringLength se listan en la tabla 9.12:

Por defecto, el validador StringLength no considera a ninguna cadena de caracteres como valida. Usamos el método setMin() para indicar el limite inferior y el método setMax() para indicar el limite superior de la longitud de la cadena de caracteres permitida. Existen tres maneras posibles de hacer esto.

• Usar solamente el método setMin() para permitir cadenas de caracteres con un limite inferior mínimo, pero sin limite de longitud superior.
• Usar solo el método setMax() para permitir cadenas de caracteres con una longitud mínima cero y una longitud máxima limite.
• Usar ambos métodos, setMin() y setMax(), para permitir cadenas de caracteres con un longitud entre el límite inferior y el superior.

Por defecto, el motor de PHP usa codificación UTF-8 para las cadenas de caracteres. Si nuestra cadena de caracteres de entrada usa una codificaciones diferente, debemos especificarla con el método del validador setEncoding().

Abajo, mostramos un código de ejemplo del uso del validador StringLength.

<?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. Organizar los validadores en una cadena

Los validadores se pueden organizar en una cadena. Esto es posible con el uso de la clase ValidatorChain. Cuando un validador compuesto se ejecuta, el valor de entrada se pasa a cada validador por turno. El método isValid() del validador ValidatorChain regresa true si todos los validadores en la cadena regresan true, de lo contrario regresa false.

La clase ValidatorChain es usada internamente por la clase contenedor InputFilter para almacenar la secuencia de validadores asociados a un campo del modelo del formulario.

Los métodos públicos que provee la clase ValidadorChain se presentan en la tabla 9.13:

Un ejemplo de validadores en cadena se muestra en la figura 9.2. Consiste en el validador NotEmpty seguido por el validador StringLength que a su vez está seguido por el validador Date. Cuando esta cadena se ejecuta, primero, el validador NotEmpty revisa que el valor no sea un valor vacío, luego el validador StringLength revisa que la longitud de la cadena de caracteres este en el rango (1, 16); ambos inclusive; y finalmente, el validador Date revisa que el valor de entrada es una fecha con formato «YYYY-MM-DD».

Figura 9.2. Cadena validadora

Para construir una cadena de validación como la de la figura 9.2, podemos usar el siguiente código:

<?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. Validador personalizado con el validador Callback

El validador Callback puede ser un envoltorio para nuestro algoritmo de validación personalizado. Por ejemplo, puede ser útil cuando un validador no es apropiado y necesitamos aplicar nuestro propio algoritmo de revisión a los datos. Los métodos públicos provistos por el validador Callback se listan en la tabla 9.14.

Como se puede ver en la tabla, el validador Callback provee los métodos setCallback() y setCallbackOptions() que se pueden usar para colocar las funciones de retro llamada o métodos de una clase (opcionalmente) y pasarles uno o varios valores parámetros.

9.6.4.1. Ejemplo

Para demostrar el uso del validador Callback, vamos a agregar un validador al número de teléfono de nuestra clase de modelo de formulario ContactForm. Este validador revisará el número de teléfono ingresado por el visitante del sitio.

El validador debe ser capaz de revisar dos tipos de formato de número telefónico comunes:

• El formato internacional que se ve: «1 (234) 567-8901»;
• El formato local, que tiene el siguiente aspecto «567-8901».

Como ZF3 no provee un validador estándar que filtre el número de teléfono, usaremos el validador Callback como envoltorio. Para conseguirlo, hacemos los siguientes cambios al código de nuestra clase ContactForm:

<?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;
  }
}

En el código de arriba, creamos el campo phone en nuestro ContactForm (Si ya tenemos este campo, podemos ignorar este paso)

Entre las líneas 26-40, agregamos el validador Callback a la cadena de validación de filtros de entrada para el campo «phone».

En las líneas 44-64, tenemos el método de retro llamada validatePhone(). Este método acepta tres argumentos: el parámetro $value es el número de teléfono a validar, la variable $context recibe los valores de cada campo del formulario (puede ser necesario para algunos validadores, revisar los valores de otro campos del formulario) y el parámetro $format es el formato esperado para el número de teléfono («intl» o «local»).

Dentro del método de retro llamada, hacemos lo siguiente:

1. Calcular la longitud del número de teléfono, revisar si la longitud es correcta para el formato de número de teléfono seleccionado.
2. Comparar el número de teléfono contra una expresión regular de acuerdo con el formato de número de teléfono seleccionado.