Symfony/Validator para PHP: guia completo com exemplos práticos

1. O que é e para que serve

A biblioteca Symfony/Validator é um componente poderoso e flexível do ecossistema Symfony, projetado para validação de dados. Diferente de verificações simples "na hora", este componente oferece uma abordagem declarativa: você descreve as regras de validação (restrições) usando anotações, atributos do PHP 8+, YAML, XML ou arrays PHP, e então passa os dados para um serviço especial — o ValidatorInterface. Isso permite separar a lógica de validação da lógica de negócios da aplicação, tornando o código mais limpo, testável e reutilizável.

Por que isso é necessário? Em qualquer aplicação web (e não só), os dados vêm de fontes não confiáveis: formulários no site, requisições de API, importação de arquivos CSV. Sem validação, você corre o risco de sofrer ataques de SQL injection, XSS, cálculos incorretos ou simplesmente acumular "lixo" no banco de dados. O Symfony/Validator resolve esses problemas de forma abrangente: ele verifica tipos de dados, comprimentos de strings, intervalos numéricos, unicidade de e-mail, conformidade com expressões regulares e muito mais. Além disso, ele coleta todos os erros em um único objeto ConstraintViolationList, que pode ser facilmente convertido em uma resposta JSON para API ou exibido como uma lista de erros em um formulário.

O componente é totalmente independente do framework Symfony. Você pode usá-lo em qualquer projeto PHP (Laravel, Yii, seu próprio framework ou até mesmo PHP "puro"). Ele é ativamente mantido, possui documentação excelente e uma comunidade enorme. É o "padrão ouro" de validação no mundo PHP.

2. Instalação

A instalação é feita via Composer. Execute no terminal, na raiz do seu projeto:

composer require symfony/validator

Também é recomendado instalar o componente symfony/property-access para garantir o funcionamento correto com objetos e arrays aninhados:

composer require symfony/property-access

Se você planeja usar anotações/atributos, certifique-se de ter o doctrine/annotations instalado (para PHP 7.x) ou esteja usando PHP 8+ com atributos nativos.

3. Início rápido — exemplo funcional mínimo

Vamos criar uma classe simples User com atributos de validação e testá-la.

<?php
// 1. Inclui o autoload do Composer
require_once 'vendor/autoload.php';

// 2. Importa as classes necessárias
use Symfony\Component\Validator\Validation;
use Symfony\Component\Validator\Constraints as Assert;

// 3. Cria a classe com atributos de validação (PHP 8+)
class User {
    #[Assert\NotBlank(message: "O nome não pode estar vazio")]
    #[Assert\Length(min: 2, max: 50, minMessage: "O nome deve ter no mínimo {{ limit }} caracteres")]
    public string $name;

    #[Assert\NotBlank]
    #[Assert\Email(message: "O e-mail '{{ value }}' não é válido.")]
    public string $email;

    #[Assert\PositiveOrZero]
    public int $age;
}

// 4. Cria o validador
$validator = Validation::createValidatorBuilder()
    ->enableAttributeMapping() // Habilita o suporte a atributos
    ->getValidator();

// 5. Cria um objeto com dados inválidos
$user = new User();
$user->name = 'A'; // Nome muito curto
$user->email = 'not-an-email';
$user->age = -5;

// 6. Valida
$violations = $validator->validate($user);

// 7. Processa os erros
if (count($violations) > 0) {
    foreach ($violations as $violation) {
        echo $violation->getPropertyPath() . ': ' . $violation->getMessage() . "\n";
    }
} else {
    echo "Dados válidos!";
}

Este exemplo exibirá:

name: O nome deve ter no mínimo 2 caracteres
email: O e-mail 'not-an-email' não é válido.
age: Este valor deve ser positivo ou igual a zero.

4. Principais métodos/funções/classes

4.1. Validation::createValidatorBuilder()

Assinatura: