8.6. Ejemplos del uso de los filtros

Ahora vamos a ver el uso de los más importantes filtros estándares. Describimos los métodos (y opciones) que un filtro tiene y damos código de ejemplo que muestra como instanciar el filtro y colocarle datos de entrada. Si necesitas usar un filtro que no está explicado en esta sección, puedes revisar la sección Standard Filters del Zend Framework Reference Manual.

8.6.1. Filtros que transforman datos a un tipo específico

En esta sección revisaremos varios filtros de un grupo de filtros relacionados con la transformación de los datos de entrada a un tipo específico y damos un ejemplo de su uso.

8.6.1.1. El filtro ToInt

El filtro ToInt es un filtro muy simple que está diseñado para convertir datos escalares a un entero. Este filtro puede ser útil cuando agregamos reglas de validación para campos de formulario que deben contener un valor numérico entero (por ejemplo, un menú desplegable o un campo de texto que contiene una cantidad de algo).

La clase ToInt tiene un único método filter().

El filtro ToInt no convierte valores no escalares. Si le pasamos un arreglo el filtro regresará el arreglo sin modificaciones.

Abajo, encontraremos un ejemplo que ilustra el uso del filtro ToInt.

<?php
// Create ToInt filter.
$filter = new \Zend\Filter\ToInt();

// Filter a value casting it to an integer number.
$filteredValue = $filter->filter('10'); // Returns (int) 10.
$filteredValue2 = $filter->filter(['10', '20']); // Returns array as is.

En el código de arriba pasamos la cadena de caracteres "10" al filtro (línea 6). El valor que se espera que regrese es el entero 10.

En la línea 7 pasamos un arreglo al filtro. Como el filtro Int solo trabaja con valores escalares regresará el arreglo sin cambios y generará una advertencia de PHP.

8.6.1.2. El filtro Boolean

La clase Boolean es una filtro que está diseñado para convertir datos a un valor booleano (true o false). Este filtro puede ser usado para revisar campos del formulario que son casillas de verificación.

Sus métodos públicos son listados en la tabla 8.3.

Los filtros provee varios métodos que permiten colocar las opciones del filtro (setCasting(), setType() y setTranslations()).

El método setCasting permite elegir uno de los dos modos en que el filtro puede operar. Si la bandera es true el filtro se comportará como el operador de conversión (boolean) de PHP. Si la bandera se coloca en false solo se convertirá con tipos de datos definidos por el método setType() y todos los otros valores se regresarán sin cambios.

El método de filtro setType() permite definir a que tipos de datos hacer la conversión. Este método acepta un solo argumento $type, que puede ser una combinación OR de constantes TYPE_- o un arreglo que contiene el equivalente literal de las constantes. Las posibles constantes aceptadas por el método setType() y sus equivalentes literales se listan en la tabla 8.4:

El código siguiente muestra dos maneras equivalentes de llamar al método setType():

<?php
use Zend\Filter\Boolean;

// Call the setType() and pass it a combination of constants.
$filter->setType(Boolean::TYPE_BOOLEAN|
                 Boolean::TYPE_INTEGER|
                 Boolean::TYPE_STRING);

// Call the setType() and pass it an array with literal equivalents.
$filter->setType(['boolean', 'integer', 'string']);

El método setTranslations() permite definir el equivalente de la Configuración Regional de un booleano true o false. Este método acepta un solo parámetro que debe ser un arreglo con la forma de un par llave=>valor, donde la llave es la cadena de caracteres que identifica la Configuración Regional y el valor es su representación booleana. El siguiente ejemplo muestra como usar el método setTranlsations():

<?php
$filter->setTranslations([
  'yes' => true,    // English 'yes'
  'no'  => false,   // English 'no'
  'ja'  => true,    // German 'yes'
  'nicht' => false, // German 'no'
  'да'  => true,    // Russian 'yes'
  'нет' => false    // Russian 'no'
  ]);

Abajo, mostramos un ejemplo que ilustra el uso del filtro Boolean.

<?php
// Create ToBoolean filter.
$filter = new \Zend\Filter\Boolean();

// Optionally configure the filter.
$filter->setCasting(true);
$filter->setType(\Zend\Filter\Boolean::TYPE_ALL);
$filter->setTranslations(['yes'=>true, 'no'=>false]);

// Filter a value casting it to a boolean number.
$filteredValue = $filter->filter('false'); // Returns boolean false.
$filteredValue2 = $filter->filter('1'); // Returns boolean true.
$filteredValue3 = $filter->filter('false'); // Returns boolean false.
$filteredValue4 = $filter->filter('yes'); // Returns boolean true.

8.6.1.3. Filtro ToNull

El filtro ToNull está diseñado para convertir datos arbitrarios a un valor null cuando los datos cumplen con un criterio específico. Esto puede ser útil cuando trabajamos con bases de datos y queremos tener un valor null en lugar de cualquier otro tipo. Si el valor no puede ser tratado como null el filtro regresará el valor sin modificarlo.

Los métodos públicos del filtro ToNull se muestran en la tabla 8.5.

Por defecto, el filtro ToNull se comporta como la función empty() de PHP: si la función empty() regresa el booleano true a partir de los datos de entrada entonces con los mismos datos el filtro regresará el valor null.

El método setType() se puede usar para colocar el tipo de dato desde el que se convertirá a null. Este método toma un solo parámetro que puede ser una combinación de las constantes TYPE_- que se muestran en la tabla 8.6 o un arreglo con sus equivalentes literales.

El siguiente ejemplo ilustra dos maneras equivalentes de llamar al método setType():

<?php
use Zend\Filter\ToNull;

// Call the setType() and pass it a combination of constants.
$filter->setType(ToNull::TYPE_ZERO_STRING|ToNull::TYPE_STRING);

// Call the setType() and pass it an array with literal equivalents.
$filter->setType(['zero', 'string']);

Abajo, mostramos un ejemplo de como usar el filtro ToNull:

<?php
// Create ToNull filter.
$filter = new \Zend\Filter\ToNull();

// Optionally configure the filter.
$filter->setType(\Zend\Filter\ToNull::TYPE_ALL);

$filteredValue = $filter->filter('0'); // Returns null.
$filteredValue2 = $filter->filter('1'); // Returns string '1'.
$filteredValue3 = $filter->filter(false); // Returns null.

8.6.1.4. El filtro DateTimeFormatter

El filtro DateTimeFormatter acepta una fecha en un formato arbitrario y lo convierte al formato deseado.

Este filtro puede aceptar una cadena de caracteres (por ejemplo, '2014-03-22 15:36'), una marca de tiempo de tipo entero (como la que regresa la función time() de PHP) o una instancia de la clase DateTime de PHP. El filtro DateTimeFormatter puede producir una excepción Zend\Filter\Exception\InvalidArgumentException si le pasamos una fecha en un formato incorrecto.

Los métodos públicos del filtro se muestran en la tabla 8.7.

En el ejemplo de abajo mostramos como crear un filtro, pasarle una cadena de caracteres con una fecha y convertirla al formato deseado:

<?php
// Create DateTimeFormatter filter.
$filter = new \Zend\Filter\DateTimeFormatter();

// Set filter's format (optional).
$filter->setFormat('F j, Y g:i A');

// Transform the date to the specified format.
$filteredValue = $filter->filter('2014-03-22 15:36');

// The expected output is 'March 22, 2014 3:36 PM'.

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

8.6.2. Filtros que ejecutan manipulaciones sobre una ruta de archivo

En este sección consideraremos el uso de los filtros del grupo encargado de manipular la ruta de los archivos.

8.6.2.1. El filtro BaseName

La clase filtro BaseName es solo una envoltura sobre la función de PHP basename(). La función toma una cadena de caracteres que contiene la ruta a un archivo o carpeta y regresa el último nombre del que está compuesto.

Abajo, podemos encontrar un ejemplo del uso del filtro BaseName:

<?php
// Create BaseName filter.
$filter = new \Zend\Filter\BaseName();

// Filter a file path and return its last part.
$filteredValue = $filter->filter('/var/log/httpd/error.log');

// The expected filter's output is the 'error.log'.

La filtro BaseName no procesará valores no escalares. Si pasamos un arreglo el filtro regresará el arreglo sin modificaciones y producirá una advertencia de PHP.

8.6.2.2. El filtro Dir

La clase filtro Dir es solo una envoltura de la función de PHP dirname(). Esta toma una cadena de caracteres que contiene la ruta a un archivo o carpeta y regresa la carpeta padre de la ruta.

El filtro Dir no procesa valores no escalares. Si pasamos un arreglo el filtro regresará el arreglo sin modificaciones.

Abajo mostramos un ejemplo que demuestra el uso del filtro Dir.

<?php
// Create Dir filter.
$filter = new \Zend\Filter\Dir();

// Filter a file path and return its directory name part.
$filteredValue = $filter->filter('/var/log/httpd/error.log');

// The expected filter's output is the '/var/log/httpd'.

8.6.2.3. El filtro RealPath

El filtro RealPath toma como argumento de entrada una ruta relativa o absoluta a un archivo. Este filtro expande todos los enlaces simbólicos y resuelve las referencias a '/./', '/../' y los caracteres extra '/' de la ruta de entrada y regresa la ruta absoluta del nombre canónico.

El filtro RealPath es un envoltorio sobre la función de PHP realpath().

Los métodos públicos del filtro se muestran en la tabla 8.8.

El filtro RealPath regresa un booleano false en caso de falla, por ejemplo, cuando el archivo no existe. Si se permiten los archivos inexistentes podemos llamar al método setExists() con el parámetro false.

Abajo mostramos un ejemplo que demuestra el uso del filtro RealPath.

<?php
// Create RealPath filter.
$filter = new \Zend\Filter\RealPath();

// Filter a file path (it is assumed that the current
// working directory is /var/log/httpd and that it contains
// the error.log file).
$filteredValue = $filter->filter('./error.log');

// The expected filter's output is the '/var/log/httpd/error.log'.

El filtro RealPath no procesa valores no escalares. Si le pasamos un arreglo lo regresará sin hacer modificaciones.

8.6.3. Filtros que ejecutan compresión y codificación de los datos de entrada

En esta sección consideraremos varios filtros del grupo de filtros que comprimen y codifican los datos de entrada. Estos filtros no son muy útiles para filtrar datos del formulario pero se pueden usar fuera de los formularios con buenos resultados.

8.6.3.1. El filtro Compress

El filtro Compress está diseñado para comprimir los datos de entrada con algún algoritmo de compresión. Por ejemplo, podemos usar este filtro para comprimir los datos y guardarlos en un paquete de archivos.

Los métodos públicos del filtro se muestran en la tabla 8.9.

El filtro Compress en sí mismo no comprime los datos. En su lugar él usa la clase adaptador. La clase adaptador debe implementar la interfaz CompressionAlgorithmInterface. Luego, se une un adaptador a un filtro Compress y el adaptador implementa el algoritmo de compresión concreto.

Existen varias clases adaptadoras estándares disponibles (figura 8.2 y tabla 8.10). Estas clases se encuentran en el espacio de nombres Zend\Filter\Compress.

Figura 8.2. Herencia del adaptador de compresión

Abajo, mostramos un ejemplo del uso del filtro Compress.

<?php
// Create Compress filter.
$filter = new \Zend\Filter\Compress();

// Configure the adapter.
$filter->setAdapter('Zip');
$filter->setAdapterOptions([
        'archive' => 'example.zip',
    ]);

// Compress an input data (it is assumed that you have the testfile.txt
// file in the current working directory.
$filter->filter('testfile.txt');

En el código de arriba creamos una instancia del filtro Compress (línea 3), colocamos su adaptador (línea 6), colocamos las opciones del adaptador (línea 7) y finalmente comprimimos el archivo de entrada (línea 13). El resultado esperado, un paquete de archivos example.zip, será creado en el carpeta actual. El paquete de archivos contiene el archivo testfile.txt.

El filtro Decompress es un «espejo reflector» del filtro Compress y se puede usar análogamente. Por esta razón no cubrimos el filtro Decompress en esta sección.

8.6.3.2. El filtro Encrypt

El propósito del filtro Encrypt es codificar los datos de entrada con el algoritmo especificado. Los métodos públicos del filtro se muestran en la tabla 8.11.

El filtro Encrypt usa clases adaptadoras para ejecutar la codificación de los datos. Asignamos un adaptador al filtro Encrypt con el método setAdapter() y el adaptador ejecuta el cifrado.

La clase adaptador debe implementar la interfaz EncryptionAlgorithmInterface.

Existen varias clases adaptadoras estándares disponibles (ver la figura 8.3). Estas clases están en el espacio de nombres Zend\Filter\Encrypt.

• BlockCipher -- implementa un algoritmo de cifrado por bloques simétrico.
• Openssl -- usa el algoritmo de cifrado de la biblioteca OpenSSL.

Figura 8.3. Herencia del adaptador de cifrado

Abajo, tenemos un ejemplo que demuestra el uso del filtro Encrypt.

<?php
// Create Encrypt filter.
$filter = new \Zend\Filter\Encrypt();

// Set encryption adapter.
$filter->setAdapter('BlockCipher');

// Encrypt an input data.
$filteredValue = $filter->filter('some data to encrypt');

El resultado esperado es una cadena de caracteres cifrada con cifrado por bloques.

El filtro Decrypt es un «espejo reflector» del filtro Encrypt y se puede usar de manera análoga. Por esta razón, no discutimos el funcionamiento del filtro Decrypt en esta sección.

8.6.4. Filtros que manipulan cadenas de caracteres

En esta sección consideraremos los filtros del grupo de filtros que manipulan cadenas de caracteres.

8.6.4.1. El filtro StringToLower

La clase filtro StringToLower está diseñada para convertir los datos de entrada que son cadenas de caracteres a letras minúsculas. Los métodos públicos del filtro se muestran en la tabla 8.12 más abajo.

Por defecto, el filtro se comporta como la función strtolower() de PHP. Dado una cadena, el filtro regresa la cadena con los caracteres alfabéticos convertidos a minúsculas. Los «caracteres alfabéticos» son determinados por la Configuración Regional del sistema. Esto significa que, por ejemplo, la Configuración Regional por defecto «C» no convertirá el carácter umlaut-A (Ä).

Cuando llamamos al método setEncoding() junto con la codificación forzamos al filtro a comportarse como la función mb_strtolower() de PHP. En constaste con la función strtolower(), el «alfabeto» se determina con las propiedades de los caracteres Unicode. En este caso el comportamiento de esta función no es afectada por la Configuración Regional y puede convertir cualquier carácter «alfabético», como A-umlaut (Ä).

Si el valor dado no es un escalar, el valor se mantendrá sin filtrar y se producirá un E_USER_WARNING indicando que no se pudo filtrar.

Abajo, mostramos un ejemplo de como usar el filtro StringToLower:

<?php
// Create StringToLower filter.
$filter = new \Zend\Filter\StringToLower();

// (Optionally) set encoding on the filter.
$filter->setEncoding('UTF-8');

// Filter a string.
$filteredValue = $filter->filter('How to Start a Business in 10 Days');

// The expected filter's output is the 'how to start a business in 10 days'.

El filtro StringToUpper (convierte una cadena de caracteres a letras mayúsculas) es un «espejo reflectante» del filtro StringToLower y se puede usar análogamente. Por esta razón, no cubrimos el filtro StringToUpper en esta sección.

8.6.4.2. Filtro PregReplace

El filtro PregReplace se puede usar para buscar y reemplazar una cadena de caracteres usando un expresión regular. Este filtro es una envoltura sobre la función de PHP preg_replace() PHP. Los métodos públicos del filtro se muestran en la tabla 8.13 más abajo.

Abajo, se muestra un ejemplo de como usar el filtro PregReplace:

<?php
// Create PregReplace filter.
$filter = new \Zend\Filter\PregReplace();

// Configure the filter.
$filter->setPattern("/\s\s+/");
$filter->setReplacement(' ');

// Filter a string.
$filteredValue = $filter->filter('An example    with    multiple     spaces.');

// The expected filter's output is the 'An example with multiple spaces.'

8.6.4.3. El filtro StripTags

El filtro StripTags remueve todas las etiquetas (por ejemplo, <!-- -->, <p>, <h1> or <?php ?>) que puede contener las cadenas de caracteres que son ingresadas en el formulario. El filtro nos permite definir explícitamente las etiquetas que no deben ser eliminadas. Además, el filtro permite especificar que atributos se permiten tanto a todas las etiquetas como a etiquetas especificas.

Los métodos públicos del filtro StripTags se listan en la tabla 8.14.

Abajo, mostramos un ejemplo de como usar el filtro StripTags:

<?php
// Create StripTags filter.
$filter = new \Zend\Filter\StripTags();

// Configure the filter.
$filter->setTagsAllowed(['p']);

// Filter a string.
$filteredValue = $filter->filter(
  '<p>Please click the following <a href="example.com">link</a>.</p>');

// The expected filter's output is the
// '<p>Please click the following link.</p>;'

El filtro StripTags no procesa valores no escalares. Si el valor que se pasa al filtro no es un escalar el valor permanecerá sin filtrar.

8.6.4.4. El filtro StripNewlines

El filtro StripNewlines es un filtro muy simple que regresa la cadena de caracteres de entrada sin los caracteres de control de nueva línea ("\r", "\n").

Abajo, mostramos un código de ejemplo que muestra como usar el filtro StripNewlines:

<?php
// Create StripNewlines filter.
$filter = new \Zend\Filter\StripNewlines();

// Filter a string.
$filteredValue = $filter->filter("A multi line\r\n string");

// The expected filter's output is the 'A multi line string'.

El filtro StripNewlines no procesa valores no escalares. Si el valor pasado al filtro no es un escalar el valor permanecerá sin filtrar.

8.6.4.5. El filtro UriNormalize

El filtro UriNormalize se puede usar para normalizar la URL y opcionalmente asignar un esquema a la URL. Los métodos públicos del filtro se muestran más abajo en la tabla 8.15.

El proceso de normalización de la URL consiste generalmente de los siguientes pasos:

1. La cadena de caracteres en que está compuesta la URL se descompone en su esquema, servidor, número de puerto, ruta y consulta. Si la parte del esquema no está en la URL original se usa el esquema por defecto.
2. La parte del esquema y la del servidor se convierte a letras minúsculas.
3. El número del puerto es contrastado contra la lista de puertos permitidos, si no pertenece a la lista el número de puerto se renueve.
4. La parte de la ruta de la URL se filtra, removiendo los puntos redundantes, se decodifica cualquier carácter sobre-codificado y se codifica todo lo que necesita estar codificado.
5. La parte de la consulta se limpia, se decodifica todo lo que no necesita estar codificado y se codifica todo lo que debe estar codificado.

Las reglas del proceso de normalización de la URL puede ser diferente para cada protocolo (esquema). Si la URL no contiene la parte del esquema, el esquema http se usa por defecto. Podemos usar el método setDefaultScheme() del filtro UriNormalize para colocar el esquema por defecto para la normalización de la URL. Este método acepta cualquiera de los siguientes esquemas: http, https, file, mailto, urn y tag.

Además, el método setEnforcedScheme() del filtro UriNormalize permite sobrescribir la parte del esquema por un «esquema forzado» si la URL no contiene la parte del esquema.

Abajo, mostramos un ejemplo de como usar el filtro UriNormalize:

<?php
// Create UriNormalize filter.
$filter = new \Zend\Filter\UriNormalize();

// Configure the filter.
$filter->setDefaultScheme('http');
$filter->setEnforcedScheme('https');

// Filter an URL string.
$filteredValue = $filter->filter('www.example.com');

// The expected filter's output is the 'https://www.example.com/'.

8.6.5. Organizar los filtros en una cadena

Los filtros se pueden organizar en secuencias. Esto se lleva a cabo por medio de la clase FilterChain. Cuando este filtro compuesto se ejecuta, el valor filtrado por el primer filtro se pasa como entrada para el segundo filtro, luego el valor filtrado por el segundo filtro se pasa al tercer filtro y así sucesivamente.

La clase FilterChain es usada internamente por la clase contenedor InputFilter para guardar la secuencia de filtros asociados al campo del modelo de formulario.

Los métodos públicos que provee la clase FilterChain se muestran en la tabla 8.16:

En la figura 8.4 se muestra un ejemplo de una cadena de filtro. La cadena consiste en el filtro StringTrim seguido por el filtro StripTags que a su vez es seguido por el filtro StripNewlines.

Figura 8.4. Cadena de filtro

Para construir una cadena de filtro como la de la figura 8.4 podemos usar el siguiente código:

<?php
use Zend\Filter\FilterChain;

// Instantiate the filter chain.
$filter = new FilterChain();

// Insert filters into filter chain.
$filter->setOptions([
    'filters'=>[
        [
            'name'=>'StringTrim',
            'options'=>['charlist'=>"\r\n\t "],
            'priority'=>FilterChain::DEFAULT_PRIORITY
        ],
        [
            'name'=>'StripTags',
            'options'=>['tagsallowed'=>['p']],
            'priority'=>FilterChain::DEFAULT_PRIORITY
        ],
        [
            'name'=>'StripNewlines',
            'priority'=>FilterChain::DEFAULT_PRIORITY
        ]
    ]
]);

// Execute all filters in the chain.
$filteredValue = $filter->filter("  name@example.com<html>\n ");

// The expected output is 'name@example.com'.

En el código de arriba instanciamos el filtro FilterChain con el operador new (línea 5). En la línea 8, construimos la cadena de filtros con el método setOptions().

El método toma una arreglo de configuración como el que recibe el método add() del filtro InputFilter. El arreglo tiene la llave «filters» en donde registramos los filtros que queremos insertar en la cadena. Para cada filtro que se asocia debemos proveer las siguientes subllaves:

• «name» es el nombre completo de la clase del filtro (por ejemplo, StringTrim::class) o su alias (ejemplo, «StringTrim»).
• «options» es un arreglo de opciones que se pasan al filtro.
• «priority» es una clave opcional que define la prioridad del filtro dentro de la cadena. Los filtros con alta prioridad son ejecutados primero. El valor por defecto para la prioridad es DEFAULT_PRIORITY.

Finalmente, en la línea 28 llamamos al método filter() que recorre la cadena y pasa el valor filtrado a cada filtro a su turno.

8.6.6. Filtros a la medida con el filtro Callback

Los filtros estándares están diseñados para ser usados en las situaciones más comunes. Por ejemplo, a menudo necesitamos cortar una cadena de caracteres o convertirla a letras minúsculas. Sin embargo, algunas veces hay casos en donde no podemos usar un filtro estándar. En estos casos el filtro Callback será útil.

El filtro Callback está diseñado como un envoltorio para nuestros algoritmos de filtrado. Por ejemplo, el filtro Callback puede ser útil cuando un filtro estándar no es apropiado y necesitamos aplicar nuestro propio algoritmo de filtrado a los datos.

Un algoritmo de filtrado a la medida se implementa como una función de retrollamada o como un método de retrollamada en una clase. Una retrollamada es una función o un método público, que es llamado por el filtro Callback, al que se le pasa el valor que será filtrado y opcionalmente argumentos definidos por el usuario.

Los métodos públicos que provee la función Callback se listan en la tabla 8.17.

Como podemos ver en la tabla el filtro Callback provee los métodos setCallback() y setCallbackParams() que se pueden usar para colocar las funciones de retrollamada (o los métodos de retrollamada de una clase) y opcionalmente pasarle uno o más parámetros.

8.6.6.1. Ejemplo

Para demostrar el uso del filtro Callback vamos a agregar el campo número de teléfono a nuestra clase modelo de formulario ContactForm y le añadiremos el filtro personalizado.

Un número de teléfono internacional típico tiene el aspecto siguiente «1 (808) 456-7890». Este consiste en el código del país seguido por un código de área de tres dígitos encerrados entre paréntesis. El resto de número consiste en siete dígitos que corresponden al código del suscriptor dividido en dos grupos que se separan con un guión. El código de país, el código de área y el código del suscriptor se separan con un espacio. Nos referiremos a este formato de número de teléfono como el formato «internacional».

El formato de número internacional se necesita para hacer llamadas entre diferentes países (o áreas). Si las llamadas son hechas dentro de la misma área el número puede ser simplemente «456-7890» (solo omitimos el código del país y el código de área). Nos referiremos a este formato como el formato de número «local».

Para hacer a nuestro filtro tan genérico como sea posible asumiremos que el usuario necesita ingresar el número en el formato internacional en algunos formularios y en formato local en otros. Como algunos usuarios pueden ingresar su número de teléfono en un formato diferente al que es requerido, queremos aplicar un filtro que «normalice» el número de teléfono por nosotros.

Para «normalizar» el número de teléfono, el filtro debe:

1. Quitar cualquier carácter no numérico del valor de entrada.
2. Rellenar los dígitos faltantes si hay pocos dígitos.
3. Agregar los paréntesis, los espacios y el guión (cuando se usa el formato internacional) o simplemente agregar el guión (cuando se usa el formato local).

Como ZF3 no provee un filtro estándar para filtrar el teléfono, usaremos el filtro de envoltura Callback. Para hacerlo, haremos los siguientes cambios en el código de la 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,
        'filters'  => [
          [
            'name' => 'Callback',
            'options' => [
              'callback' => [$this, 'filterPhone'],
              'callbackParams' => [
                'format' => 'intl'
              ]
            ]
          ],
        ],
      ]);
  }

  // Custom filter for a phone number.
  public function filterPhone($value, $format)
  {
    if(!is_scalar($value)) {
      // Return non-scalar value unfiltered.
      return $value;
    }

    $value = (string)$value;

    if(strlen($value)==0) {
      // Return empty value unfiltered.
      return $value;
    }

    // First, remove any non-digit character.
    $digits = preg_replace('#[^0-9]#', '', $value);

    if($format == 'intl') {
      // Pad with zeros if the number of digits is incorrect.
      $digits = str_pad($digits, 11, "0", STR_PAD_LEFT);

      // Add the braces, the spaces, and the dash.
      $phoneNumber = substr($digits, 0, 1) . ' ('.
                     substr($digits, 1, 3) . ') ' .
                     substr($digits, 4, 3) . '-'.
                     substr($digits, 7, 4);
    } else { // 'local'
      // Pad with zeros if the number of digits is incorrect.
      $digits = str_pad($digits, 7, "0", STR_PAD_LEFT);

      // Add the dash.
      $phoneNumber = substr($digits, 0, 3) . '-'. substr($digits, 3, 4);
    }

    return $phoneNumber;
  }
}

En las líneas 11-20 del código de arriba, agregamos el campo «phone» al modelo de formulario ContactForm. El campo es usualmente un campo de entrada de texto y ya tenemos algo de experiencia trabajando con este tipo de campos antes.

Luego, en las líneas 26-40, agregamos una regla de validación para el campo «phone» de nuestro formulario. Dentro de la llave «filters» (línea 29) registramos el filtro Callback (usamos el alias Callback, pero podemos también usar el nombre completo de la clase Callback::class).

El filtro toma dos opciones (línea 32): la opción «callback» y la opción «callback_params». La opción «callback» es un arreglo que consiste en dos elementos que representan respectivamente a la clase y el método que se llama. En este ejemplo, la retrollamada es al método filterPhone() de la clase ContactForm. Pasamos el parámetro «format» al método de retrollamada con la ayuda de la opción «callbackParams» (línea 34).

En las líneas 44-79, definimos el método de retrollamada filterPhone() que toma dos argumentos: el $value es el número de teléfono a filtrar y el $format es el formato de número deseado. El parámetro $format puede ser o «local» (para un formato local) o «intl» (para un formato internacional).

Con el método de retrollamada filterPhone() hacemos lo siguiente:

• Primero, en la línea 46, revisamos si el parámetro $value es un escalar y no un arreglo. Si el valor no es un escalar lo regresamos sin cambiarlo.

• En la línea 53, revisamos el tamaño del valor de entrada. No hacemos nada si el usuario ingresó un número de teléfono vacío por lo que retornamos el valor sin hacer modificaciones.

• Luego, removemos cualquier carácter que no sea un dígito (línea 59).

• Si la longitud del número es muy corta rellenamos con ceros.

• Agregamos paréntesis, el guión y los espacios para el número de teléfono internacional o solo el guión para los números de teléfono locales.

• Finalmente, regresamos el número de teléfono que resulta.

Para ver como este filtro trabaja podemos abrir la URL «http://localhost/contactus» en nuestro navegador web. Si ingresamos algún número de teléfono en un formato incorrecto, el filtro corregirá el número de teléfono y lo transformará al formato estándar.