README

Biblioteca PHP para validação de documentos e identificadores brasileiros. Sem dependência de framework — funciona em qualquer projeto PHP puro, Laravel, Symfony, etc.

Veja também as versões para outros ambientes: Laravel · JavaScript / TypeScript

Requisitos

• PHP ^8.1

Instalação

composer require casilhero/brazilian-validators

Validadores disponíveis

Inscrição Estadual — estados suportados

Os algoritmos foram verificados individualmente contra os roteiros oficiais de crítica publicados pelo SINTEGRA.

Referência técnica: SINTEGRA — Roteiros de Crítica da Inscrição Estadual

API

Todos os validadores expõem os seguintes métodos estáticos:

// Validação
Cnpj::isValid(string $value): bool
Cnpj::validate(string $value): ValidationResult

// Geração de dados de teste (retorna string sem máscara)
Cnpj::generate(): string

// Aplicação de máscara ao valor limpo
Cnpj::mask(string $value): string

Nota: InscricaoEstadual não implementa generate() nem mask() por depender de algoritmos específicos por UF. Os métodos Certidao::parse() e Boleto::parse() estão disponíveis para extrair os campos estruturados do número (ver exemplos).

ValidationResult

Retornado por validate(). Útil quando você precisa do motivo da reprovação.

$result = Suframa::validate('001234567');

$result->isValid(); // bool
$result->code();    // string|null — código de erro (veja abaixo)
$result->context(); // array — dados extras do erro

Códigos de erro

BrazilianValidator — façade estática central

Agrega todos os validadores em uma única classe para uso centralizado:

use Casilhero\BrazilianValidators\BrazilianValidator;

// Retorno bool
BrazilianValidator::cpf('529.982.247-25');
BrazilianValidator::cnpj('04.252.011/0001-10');
BrazilianValidator::cpfCnpj('04.252.011/0001-10');
BrazilianValidator::suframa('010234567');
BrazilianValidator::nisPis('12345678919');
BrazilianValidator::phone('(11) 98765-4321');
BrazilianValidator::phoneDdi('5511987654321');
BrazilianValidator::cnh('12345678900');
BrazilianValidator::cns('700009600073');
BrazilianValidator::renavam('77077411168');
BrazilianValidator::chassi('9BWZZZ377VT004251');
BrazilianValidator::tituloEleitor('123456789012');
BrazilianValidator::inscricaoEstadual('110042490114', 'SP');
BrazilianValidator::certidao('10514 01 55 2024 1 00001 092 0000250-28');
BrazilianValidator::passaporte('AB123456');
BrazilianValidator::caepf('132.574.492/00-1');
BrazilianValidator::processoJudicial('0000001-41.2024.8.01.0001');
BrazilianValidator::boleto('34191.79001 01043.510047 91020.150008 2 85480000000000');

// Retorno ValidationResult (sufixo Result)
$result = BrazilianValidator::cpfResult('11111111111');
if (! $result->isValid()) {
    echo $result->code(); // invalid_format
}

// Geração de dados de teste
$cpf    = BrazilianValidator::cpfGenerate();                // ex: '52998224725'
$cnpj   = BrazilianValidator::cnpjGenerate();               // ex: '04252011000110'
$phone  = BrazilianValidator::phoneGenerate();              // ex: '11987654321'
$cnh    = BrazilianValidator::cnhGenerate();                // ex: '12345678900'
$proc   = BrazilianValidator::processoJudicialGenerate();   // ex: '00000014120248010001'
$boleto = BrazilianValidator::boletoGenerate();             // ex: '34191790010104351004791020150008285480000000000'
// demais: cpfCnpjGenerate, suframaGenerate, nisPisGenerate, phoneDdiGenerate,
//         cnsGenerate, renavamGenerate, chassiGenerate, tituloEleitorGenerate,
//         certidaoGenerate, passaporteGenerate, caepfGenerate

// Aplicação de máscara
$maskedCpf    = BrazilianValidator::cpfMask('52998224725');    // '529.982.247-25'
$maskedCnpj   = BrazilianValidator::cnpjMask('04252011000110'); // '04.252.011/0001-10'
$maskedPhone  = BrazilianValidator::phoneMask('11987654321');  // '(11) 98765-4321'
$maskedBoleto = BrazilianValidator::boletoMask('34191790010104351004791020150008285480000000000');
//   '34191.79001 01043.510047 91020.150008 2 85480000000000'
$maskedProc   = BrazilianValidator::processoJudicialMask('00000014120248010001');
//   '0000001-41.2024.8.01.0001'
// demais: cpfCnpjMask, suframaMask, nisPisMask, phoneDdiMask, cnhMask,
//         renavamMask, chassiMask, tituloEleitorMask, certidaoMask,
//         passaporteMask, caepfMask

// Parse (extrai campos estruturados)
$certidaoInfo = BrazilianValidator::certidaoParse('10514 01 55 2024 1 00001 092 0000250-28');
$certidaoInfo?->codigoServentia;  // '10514'
$certidaoInfo?->ano;              // 2024
$certidaoInfo?->descricaoLivro(); // 'Livro A (Nascimento)'

$boletoInfo = BrazilianValidator::boletoParse('00190000090114971860168524522114675860000102656');
$boletoInfo?->type;            // 'bancario'
$boletoInfo?->bankCode;        // '001'
$boletoInfo?->amount;          // 102656
$boletoInfo?->amountInReals(); // 1026.56
$boletoInfo?->expirationDate;  // \DateTimeImmutable

Exemplos

Validação simples

use Casilhero\BrazilianValidators\Validators\Cnpj;

if (! Cnpj::isValid($request->cnpj)) {
    throw new \InvalidArgumentException('CNPJ inválido.');
}

Validação com retorno detalhado

use Casilhero\BrazilianValidators\Validators\Cns;

$result = Cns::validate($input);

if (! $result->isValid()) {
    logger()->warning('CNS inválido', ['code' => $result->code()]);
}

Geração de dados de teste

use Casilhero\BrazilianValidators\Validators\Cpf;
use Casilhero\BrazilianValidators\Validators\ProcessoJudicial;

$cpf  = Cpf::generate();               // '52998224725' (sem máscara)
$cpfF = Cpf::mask(Cpf::generate());    // '529.982.247-25' (com máscara)
$proc = ProcessoJudicial::generate();  // '00000014120248010001'
$procF = ProcessoJudicial::mask($proc); // '0000001-41.2024.8.01.0001'

Parse de certidão

use Casilhero\BrazilianValidators\Validators\Certidao;

$info = Certidao::parse('10514 01 55 2024 1 00001 092 0000250-28');
$info?->codigoServentia;  // '10514'
$info?->codigoAcervo;     // '01'
$info?->ano;              // 2024
$info?->tipoLivro;        // 1
$info?->descricaoLivro(); // 'Livro A (Nascimento)'
$info?->toArray();        // array com todos os campos

Parse de boleto

use Casilhero\BrazilianValidators\Validators\Boleto;

$info = Boleto::parse('00190000090114971860168524522114675860000102656');
$info?->type;            // 'bancario'
$info?->bankCode;        // '001'
$info?->amount;          // 102656
$info?->amountInReals(); // 1026.56
$info?->expirationDate;  // \DateTimeImmutable('2018-07-15')

Compatibilidade

Testes

composer test            # executa a suíte Pest
composer test:coverage   # executa com relatório de cobertura (mínimo 90%)
composer format          # aplica Laravel Pint
composer format:check    # verifica formatação sem alterar arquivos

Versionamento

Segue SemVer:

• MAJOR — quebra de compatibilidade na API pública
• MINOR — novas funcionalidades compatíveis com versões anteriores
• PATCH — correções sem quebra de contrato

Licença

MIT