8.3. Instanciar un filtro

En Zend Framework 3 podemos usar varios métodos para crear un filtro:

• Instanciandolo manualmente (con el operador new).
• Creándolo con una clase fábrica (pasando un arreglo de configuración), este método es él usado con mayor frecuencia cuando se agregan filtros y reglas de validación en el formulario.
• Instanciandolo implícitamente con la clase empaquetadora StaticFilter.

Más adelante cubriremos estos métodos con mayor detalle.

8.3.1. Método 1: Instanciando el filtro manualmente

Como dijimos anteriormente, en general un filtro se puede usar no solo con formularios sino también para filtrar datos arbitrarios. Para hacer esto simplemente creamos una instancia de la clase filtro, configuramos el filtro usando los métodos que provee esta clase y llamamos al método filter() en el filtro.

Por ejemplo, consideremos el uso del filtro StringTrim que quita los espacios en blanco desde el comienzo hasta el final de la cadena.

El filtro StringTrim es útil para filtrar las cadenas de caracteres ingresadas por el usuario (correo electrónico, dirección, usuario, nombres, etc.) porque los visitantes del sitio tienden a cometer errores de escritura en los datos que ingresa. Por ejemplo, un usuario puede de manera involuntaria ingresar espacios finales en el campo correo electrónico, en este caso el campo es invalido. Con el filtro StringTrim podemos manejar fácilmente este error de entrada y mejorar la experiencia del usuario.

Los métodos disponibles por el filtro se muestran en la tabla 8.2:

Como podemos ver en la tabla sobre el filtro StringTrim además del método filter() tenemos al método constructor que opcionalmente recibe una lista de opciones como valores iniciales para el filtro. Los métodos setCharList() y getCharList() se puede usar para colocar opciones especificas al filtro.

Todos los filtros estándares tienen el método constructor que opcionalmente acepta un arreglo de opciones para configurar el filtro en el caso que la instanciación sea manual.

Abajo ofrecemos dos ejemplos que muestran métodos equivalentes para la creación e instanciación manual del filtro StringTrim, colocación de sus opciones y el filtrado de un valor.

Ejemplo 1. Pasar las opciones al método constructor.

<?php
// Optionally, define a short alias for the filter class name.
use Zend\Filter\StringTrim;

// Create an instance of the filter, passing options to the constructor.
$filter = new StringTrim(['charlist'=>"\r\n\t "]);

// Perform the trimming operation on the string.
$filteredValue = $filter->filter(' name@example.com  ');

// The expected output of the filter is the 'name@example.com' string.

En el código de arriba creamos el objeto del filtro StringTrim con la ayuda del operador new (línea 6). Pasamos un arreglo de opciones al constructor para colocar la lista de los caracteres que el filtro removerá (en esta ocasión le pedimos al filtro que remueva los caracteres de nueva línea, los caracteres de tabulación y los caracteres de espacio). En realidad, se puede omitir pasar el arreglo de opciones a este filtro porque el filtro ya tiene una lista de caracteres por defecto para quitar.

En la línea 9 llamamos al método filter() y le pasamos la cadena " name@example.com " para que sea limpiada. La salida esperada de esta llamada es la cadena "name@example.com".

Ejemplo 2. Sin pasar opciones al constructor.

<?php
// Optionally, define a short alias for the filter class name.
use Zend\Filter\StringTrim;

// Create an instance of the filter.
$filter = new StringTrim();

// Specify which characters to remove.
$filter->setCharList("\r\n\t ");

// Perform the trimming operation on the string
$filteredValue = $filter->filter(' name@example.com  ');

// The expected output of the filter is the 'name@example.com' string

En el código de arriba creamos el objeto para el filtro StringTrim con la ayuda del operador new (línea 6).

En la línea 9 llamamos opcionalmente al método setCharList() del filtro StringTrim para colocar la lista de caracteres que removerá el filtro (en este caso pedimos al filtro remover los caracteres de nueva línea, los caracteres de tabulación y los caracteres de espacio). La llamada a esta función es opcional porque el filtro ya tiene una lista de caracteres por defecto para quitar.

Y en la línea 12 llamamos al método filter() y le pasamos la cadena " name@example.com " para ser limpiada. La salida esperada de esta llamada es la cadena "name@example.com".

8.3.2. Método 2: Construir un filtro con StaticFilter

Una manera alternativa de instanciar manualmente un filtro es con el uso de la clase StaticFilter. La clase StaticFilter es un tipo de «procurador» (proxy) diseñado para la instanciación, configuración y ejecución automática de filtros. Por ejemplo, si consideramos la manera de crear el mismo filtro StringTrim, configurarlo y llamar a su método filter():

<?php
// Create and execute the StringTrim filter through the StaticFilter proxy.
$filteredValue = \Zend\Filter\StaticFilter::execute(' name@example.com  ',
                        'StringTrim', ['charlist' => "\r\n\t "]);

// The expected output of the filter is the 'name@example.com' string.

La clase StaticFilter provee el método estático execute() que toma tres argumentos: el valor de entrada, el nombre del filtro a aplicar y el arreglo de opciones para el filtro seleccionado.

En la línea 3 llamamos al método execute() para crear automáticamente el filtro StringTrim, llamar a su método setCharList() y pasar el valor a su método filter(). Esto es muy útil porque todo esto puede ser ejecutado en una sola línea de código.

8.3.3. Método 3: Construcción de un filtro desde un arreglo

Cuando usamos filtros con reglas de validación de formularios generalmente no construimos un objeto de filtro explícitamente del modo como lo hicimos en la sección previa, en su lugar, pasamos un arreglo de configuración a la clase fábrica que automáticamente construye el filtro y opcionalmente lo configura por nosotros. Ya vimos como esto funciona cuando agregamos reglas de validación para el formulario de contacto en Colectar las entradas del usuario con forms.

Por ejemplo, vamos a mostrar como construir el mismo filtro StringTrim con la ayuda de una fábrica:

<?php
// It is assumed that you call the following code inside of the form model's
// addInputFilter() method.

$inputFilter->add([
  // ...
  'filters'  => [
    [
      'name' => 'StringTrim',
      'options' => [
        'charlist' => "\r\n\t "
      ]
    ],
  ],
  // ...
];

En el código de arriba llamamos al método add() que está disponible mediante la clase contenedor InputFilter (línea 5). El método add() toma un arreglo que tiene la llave filters. Generalmente registramos los filtros dentro de una llave (línea 7). Los filtros registrados en la llave se insertan en una cadena de filtros siguiendo el orden en que ellos aparecen en la lista.

La configuración de un filtro consiste generalmente en el name (línea 9) y las options (línea 10). El name corresponde al nombre completo de la clase filtro (ejemplo, Zend\Filter\StringTrim) o su alias (StringTrim). Las options son un arreglo que se compone de las opciones especificas para el filtro seleccionado. Cuando una clase fábrica instancia al filtro esta pasa la lista de opciones al método constructor del filtro y el constructor inicializa el filtro.