esdras/cdv-cnpj-alfa

dev-main 2026-04-12 15:26 UTC

MIT

• Esdras Franca

README

Uma biblioteca PHP robusta para validar números de CNPJ (Cadastro Nacional da Pessoa Jurídica) brasileiros com suporte a caracteres alfanuméricos e tratamento abrangente de erros.

Sobre CNPJ

CNPJ (Cadastro Nacional da Pessoa Jurídica) é o número de identificação fiscal de empresas brasileiras. O formato padrão do CNPJ é XX.XXX.XXX/XXXX-XX, consistindo em 14 caracteres que podem incluir dígitos (0-9) e letras (A-Z).

Esta biblioteca valida números de CNPJ através de:

• Verificação do formato correto (14 caracteres alfanuméricos)
• Validação dos dois dígitos verificadores usando o algoritmo oficial
• Detecção e rejeição de padrões inválidos

Características

✨ Validação Completa de CNPJ

• Valida números de CNPJ com 14 caracteres alfanuméricos
• Calcula e verifica ambos os dígitos verificadores
• Suporta caracteres alfanuméricos com variação de maiúsculas e minúsculas

🛡️ Tratamento Robusto de Erros

• Exceções dedicadas para diferentes cenários de erro
• Mensagens de erro claras para depuração
• Sanitização e normalização de entrada

🔧 Fácil Integração

• API simples e intuitiva
• Compatibilidade com autoloading PSR-4
• Sem dependências externas

Instalação

Via Composer

composer require esdras/cdv-cnpj-alfa

Instalação Manual

1. Clone ou faça download do projeto
2. Inclua o autoloader no seu arquivo PHP:

require_once __DIR__ . '/vendor/autoload.php';

Uso

Validação Básica

<?php

require_once __DIR__ . '/vendor/autoload.php';

use CdvCnpjAlfa\ValidadorCNPJ;

$validador = new ValidadorCNPJ();

try {
    if ($validador->validar("96.218.524/0001-22")) {
        echo "CNPJ é válido!";
    }
} catch (Exception $e) {
    echo "Erro de validação: " . $e->getMessage();
}

Tratando Exceções Específicas

A biblioteca lança exceções específicas para diferentes falhas de validação:

<?php

use CdvCnpjAlfa\ValidadorCNPJ;
use CdvCnpjAlfa\Exceptions\CnpjEmptyException;
use CdvCnpjAlfa\Exceptions\CnpjFormatException;
use CdvCnpjAlfa\Exceptions\CnpjInvalidException;

$validador = new ValidadorCNPJ();

try {
    $validador->validar($entrada);
} catch (CnpjEmptyException $e) {
    // Tratar CNPJ vazio
    echo "Erro: " . $e->getMessage(); // "O CNPJ não pode estar vazio."
} catch (CnpjFormatException $e) {
    // Tratar formato inválido (não 14 caracteres alfanuméricos)
    echo "Erro: " . $e->getMessage(); // "O formato do CNPJ é inválido."
} catch (CnpjInvalidException $e) {
    // Tratar CNPJ inválido (padrões rejeitados como caracteres repetidos)
    echo "Erro: " . $e->getMessage(); // "O CNPJ é inválido."
} catch (Exception $e) {
    // Tratar erros de validação de dígitos verificadores
    echo "Erro: " . $e->getMessage();
}

Formatos de Entrada Suportados

O validador limpa automaticamente a entrada e suporta vários formatos:

$validador->validar("96.218.524/0001-22");  // ✅ Formatado
$validador->validar("96218524000122");       // ✅ Sem formatação
$validador->validar("7M.5GG.19X/0001-58");  // ✅ Alfanumérico
$validador->validar("96.588.524/0001-22");  // ❌ Dígitos verificadores inválidos
$validador->validar("00.000.000/0000-00");  // ❌ Caracteres repetidos
$validador->validar("");                     // ❌ Entrada vazia

Limpeza Automática

O validador remove caracteres especiais e converte letras minúsculas em maiúsculas automaticamente:

$validador->validar("96.218.524/0001-22");  // Entrada formatada
$validador->validar("96218524000122");       // Entrada sem formatação
$validador->validar("96-218-524-0001-22");  // Separadores personalizados - tudo funciona!

Regras de Validação

As seguintes regras de validação são aplicadas:

1. Não Vazio: CNPJ não pode estar vazio
2. Formato: Deve conter exatamente 14 caracteres alfanuméricos (0-9, A-Z)
3. Não Repetido: Não pode ser composto por caracteres idênticos (ex: "00.000.000/0000-00", "11.111.111/1111-11")
4. Dígitos Verificadores: Os dois últimos dígitos devem ser dígitos verificadores válidos calculados de acordo com o algoritmo CNPJ

Estrutura do Projeto

cdv-cnpj-alfa/
├── src/
│   ├── ValidadorCNPJ.php          # Classe principal do validador
│   └── exceptions/
│       ├── CnpjEmptyException.php
│       ├── CnpjFormatException.php
│       └── CnpjInvalidException.php
├── public/
│   └── index.php                  # Exemplo de uso
├── vendor/                        # Dependências do Composer
├── composer.json
└── README.md

Referência da API

Classe ValidadorCNPJ

__construct()

Inicializa o validador e configura o mapeamento de caracteres ASCII para validação.

$validador = new ValidadorCNPJ();

validar(string $cnpj): bool

Valida uma string CNPJ e retorna true se válida. Lança exceções em caso de falha de validação.

Parâmetros:

• $cnpj (string): O CNPJ a validar (formatado ou sem formatação)

Retornos:

• bool: Sempre retorna true em validação bem-sucedida

Lança:

• CnpjEmptyException: Se o CNPJ está vazio
• CnpjFormatException: Se o formato do CNPJ é inválido
• CnpjInvalidException: Se o CNPJ contém todos os caracteres repetidos
• InvalidArgumentException: Se os dígitos verificadores não correspondem

try {
    $resultado = $validador->validar("96.218.524/0001-22");
    // $resultado é true
} catch (Exception $e) {
    // Tratar erro
}

Detalhes do Algoritmo

A validação do CNPJ usa o seguinte algoritmo para cálculo de dígito verificador:

1. Primeiro Dígito Verificador:

   • Multiplique cada um dos primeiros 12 dígitos por pesos 2-9 (ciclicamente)
   • Some todos os produtos
   • Calcule o resto (módulo 11)
   • Se o resto é 0 ou 1, o dígito é 0; caso contrário, dígito = 11 - resto

2. Segundo Dígito Verificador:

   • Repita o processo com os primeiros 12 dígitos + primeiro dígito verificador
   • Calcule o segundo dígito verificador

3. Validação:

   • Compare os dígitos verificadores calculados com os fornecidos

Mensagens de Erro

Exceção	Mensagem
CnpjEmptyException	O CNPJ não pode estar vazio.
CnpjFormatException	O formato do CNPJ é inválido.
CnpjInvalidException	O CNPJ é inválido.
InvalidArgumentException	CNPJ inválido: {cnpj} - dígitos verificadores não conferem

Requisitos

• PHP: 7.4 ou superior
• Sem dependências externas

Autor

Esdras Franca

• Email: [e-mail]

Licença

Este projeto é de código aberto e está disponível sob a Licença MIT.

Contribuindo

Contribuições são bem-vindas! Sinta-se livre para enviar um Pull Request ou abrir uma issue para relatar bugs e sugerir novas funcionalidades.

Exemplos

Exemplo 1: Validar Entrada do Usuário

<?php

require_once __DIR__ . '/vendor/autoload.php';

use CdvCnpjAlfa\ValidadorCNPJ;

$validador = new ValidadorCNPJ();
$cnpjs = [
    "7M.5GG.19X/0001-58",      // Válido
    "96.218.524/0001-22",      // Válido
];

foreach ($cnpjs as $cnpj) {
    try {
        if ($validador->validar($cnpj)) {
            echo "✅ $cnpj é válido\n";
        }
    } catch (Exception $e) {
        echo "❌ $cnpj: " . $e->getMessage() . "\n";
    }
}

Exemplo 2: Processamento em Lote

<?php

require_once __DIR__ . '/vendor/autoload.php';

use CdvCnpjAlfa\ValidadorCNPJ;
use CdvCnpjAlfa\Exceptions\{CnpjEmptyException, CnpjFormatException, CnpjInvalidException};

$validador = new ValidadorCNPJ();
$cnpjsValidos = [];
$cnpjsInvalidos = [];

$listaCnpjs = [
    "96.218.524/0001-22",
    "cnpj.invalido.00/0000-00",
    "",
    "11.111.111/1111-11"
];

foreach ($listaCnpjs as $cnpj) {
    try {
        $validador->validar($cnpj);
        $cnpjsValidos[] = $cnpj;
    } catch (CnpjEmptyException | CnpjFormatException | CnpjInvalidException | Exception $e) {
        $cnpjsInvalidos[$cnpj] = $e->getMessage();
    }
}

echo "Válidos: " . count($cnpjsValidos) . "\n";
echo "Inválidos: " . count($cnpjsInvalidos) . "\n";

Histórico de Alterações

Versão 1.0.0

• Lançamento inicial
• Validação de CNPJ com suporte alfanumérico
• Tratamento abrangente de exceções
• Validação de dígito verificador