Zend Filter - Aprendendo criar filtros customizados

Se você já leu a minha sequência de posts sobre o Zend Form ou já sabe como trabalhar com forms, deve conhecer o Zend Filter, certo? Hoje mostrarei como criar seus próprios filtros e vinculá-los em seus forms.

Antes de qualquer coisa

Caso ainda não saiba trabalhar com o Zend Form, sugiro a leitura destes posts:

Zend Form - Trabalhando com formulários no Zend 2 e 3 e Zend Form - Injeção de dependências. Este último é apenas um plus, não é necessário o ler para entender o que será feito aqui.

O que é o Zend Filter?

É um componente do Zend Framework que possibilita muitos tipos de filtros para uso nas mais diversas situações. Ele pode ser utilizado em formulários, "hidratação" de dados para views, etc. É possível o utilizar no ZF, outros frameworks e até mesmo sem, apenas utilizando o Composer pra gerenciar tudo.

Por que usar Zend Filter?

Um dos benefícios é que você já tem diversos filtros prontos para utilizar, tais como StringTrim, StripTags, ToInt e muitos outros, veja a lista completa no GitHub. Além de tudo o que já está pronto, você pode criar outros filtros conforme sua necessidade. São exemplos de filtros que você pode criar: aplicar/remover máscara em CPF, CNPJ, telefone, placa de veículos, números de protocolos e apólices, etc.

Estrutura básica de um filtro

namespace Application\Filter;
use Zend\Filter\FilterInterface;
class MyFilter implements FilterInterface

{

    public function filter($value)

    {

        // perform some transformation upon $value to arrive on $valueFiltered
return $valueFiltered;

    }

}

Bem simples, não? Veja no código acima que tudo o que precisamos fazer é implementar uma interface e pronto!

Vamos agora criar nosso filtro pra aplicar máscara em CPF?

CPFMaskFilter

namespace Application\Filter;
use Zend\Filter\FilterInterface;
class CPFMaskFilter implements FilterInterface

{

    /**

     * @inheritdoc

     */

    public function filter($value)

    {

        // removendo qualquer "poluição" da string e obtendo somente os dígitos

        $value = preg_replace("/\D/", '', $value);

        // Validando se o CPF possui a quantidade certa de caracteres

        if (strlen($value) !== 11) {

            return '';

        }
// Definindo padrões: 3 sequências com 3 dígitos e uma com 2

        $pattern = "/(\d{3})(\d{3})(\d{3})(\d{2})/";
// as duas primeiras sequências de 3 dígitos são separadas por um ponto, 

        // a última, por um hífen

        $replacement = "\$1.\$2.\$3-\$4";
// aplicando a máscara e retornando o valor filtrado

        return preg_replace($pattern, $replacement, $value);

    }

}

Agora é só usar no seu form filter.

InputFilter

// module/Application/src/Form/ExampleFormFilter
$inputFilter->add([

    'name' => 'cpf',

    'required' => true,

    'filters' => [

        // ...

        ['name' => \Application\Filter\CPFMaskFilter::class],

    ],

    'validators' => [

        // ...

    ],

]);

Pronto! Agora pode criar filtros conforme sua necessidade.

Como usar fora do FormFilter

O mais legal é que esse filtro não é limitado somente ao uso em Form Filters, você pode o utilizar para qualquer finalidade. Veja um exemplo de como o utilizar na view para apresentar o CPF formatado corretamente.

Primeiro cria-se um ViewHelper.

namespace Application\View\Helper;
use Application\Filter\CPFMaskFilter;

use Zend\View\Helper\AbstractHelper;
class CPFMaskViewHelper extends AbstractHelper

{

    public function __invoke($cpf)

    {

        // Este ViewHelper que criamos apenas delega o trabalho ao filtro que criamos anteriormente

        return (new CPFMaskFilter())->filter($cpf);

    }

}

Em seguida um alias para o mesmo, para utilizarmos na view.

// module/Application/src/Module.php
public function getViewHelperConfig()

{

    return [

        'invokables' => [

            // ...

            'cpfMask' => \Application\View\Helper\CPFMaskViewHelper::class

        ]

    ];

}

Na view

E por fim, o utilizando na view.

Com .phtml (padrão do Zend)

<?php echo $this->cpfMask('12345678901'); ?>

Com Twig

{{ cpfMask('12345678901') }}

Em ambos os exemplos a saída é: 123.456.789-01

That's all!

Lembre-se, filtro != validador.

Enquanto o validador tem o papel de criar asserções para uma determinada regra, o filtro apenas "hidrata" os dados recebidos. Desta forma, se por algum motivo o usuário informar um CPF como este 000.....000.000--00, somente pra testar uma possível vulnerabilidade, o filtro deixará o resultado assim: 000.000.000-00. Caso passe com um dígito a mais em qualquer posição, será feita a "limpeza" e, se o resultado for algo diferente de 11 caracteres, o retorno será uma string vazia.

Assim como já explicado nos posts anteriores sobre o Zend Form, o filtro é mais uma camada de segurança para sua aplicação. O usuário mal intencionado pode facilmente desativar o JavaScript e passar por toda e qualquer validação pelo lado do browser, mas não terá este mesmo poder com o server. Por isso é importante ter filtros e validações nas duas extremidades.