Primeiros passos

🚀 Suporte total ao novo formato alfanumérico de CNPJ.

Kit de utilitários em PHP para formatar, gerar e validar CPF (Cadastro de Pessoa Física) e CNPJ (Cadastro Nacional da Pessoa Jurídica). Oferece um wrapper de alto nível BrUtils em torno de lacus/cpf-utils e lacus/cnpj-utils, expondo todos os recursos empacotados em namespaces unificados.

Recursos

✅ API unificada de alto nível: Uma instância BrUtils com acessores de domínio $cpf e $cnpj
✅ Domínios empacotados: lacus/cpf-utils e lacus/cnpj-utils instalados juntos
✅ CNPJ alfanumérico: Suporte completo ao novo formato alfanumérico de CNPJ (a partir de 2026)
✅ Padrões configuráveis: Defina opções de formatador, gerador e (para CNPJ) validador em cada instância de domínio
✅ Sobrescrita por chamada: Sobrescreva qualquer opção de componente em uma única chamada de método
✅ Duas formas de uso: Fachada de alto nível (BrUtils), agregadores de domínio (CpfUtils, CnpjUtils), componentes isolados e helpers funcionais
✅ Namespaces compartilhados: Símbolos de CPF em Lacus\BrUtils\Cpf\; símbolos de CNPJ em Lacus\BrUtils\Cnpj\
✅ Tratamento de erros tipado: Hierarquias dedicadas de exceções dos pacotes empacotados (modelo TypeError / Exception da v2 para CNPJ; InvalidArgumentException da v1 para opções inválidas de CPF)

Instalação

# usando Composer
$ composer require lacus/br-utils

Isso instala lacus/br-utils junto com lacus/cpf-utils e lacus/cnpj-utils (que por sua vez traz os pacotes de componentes de CNPJ). Não é necessário executar composer require separado para os pacotes de domínio ao usar lacus/br-utils.

Importação

Escolha a API que melhor se adapta ao seu caso.

Fachada de alto nível:

<?php

use Lacus\BrUtils;

Agregadores de domínio:

<?php

use Lacus\BrUtils\Cpf\CpfUtils;
use Lacus\BrUtils\Cnpj\CnpjUtils;

Componentes de CPF (orientados a objeto):

<?php

use Lacus\BrUtils\Cpf\CpfFormatter;
use Lacus\BrUtils\Cpf\CpfFormatterOptions;
use Lacus\BrUtils\Cpf\CpfGenerator;
use Lacus\BrUtils\Cpf\CpfGeneratorOptions;
use Lacus\BrUtils\Cpf\CpfValidator;

Componentes de CNPJ (orientados a objeto):

<?php

use Lacus\BrUtils\Cnpj\CnpjFormatter;
use Lacus\BrUtils\Cnpj\CnpjFormatterOptions;
use Lacus\BrUtils\Cnpj\CnpjGenerator;
use Lacus\BrUtils\Cnpj\CnpjGeneratorOptions;
use Lacus\BrUtils\Cnpj\CnpjValidator;
use Lacus\BrUtils\Cnpj\CnpjValidatorOptions;
use Lacus\BrUtils\Cnpj\Enums\CnpjType as CnpjGenerationType;
use Lacus\BrUtils\Cnpj\Enums\CnpjValidationType;

Helpers funcionais:

<?php

use function Lacus\BrUtils\Cpf\cpf_fmt;
use function Lacus\BrUtils\Cpf\cpf_gen;
use function Lacus\BrUtils\Cpf\cpf_val;
use function Lacus\BrUtils\Cnpj\cnpj_fmt;
use function Lacus\BrUtils\Cnpj\cnpj_gen;
use function Lacus\BrUtils\Cnpj\cnpj_val;

Início rápido

Com BrUtils (tudo em um):

<?php

use Lacus\BrUtils;

$utils = new BrUtils();
$cpf = '11144477735';
$cnpj = '03603568000195';

$utils->cpf->format($cpf);    // '111.444.777-35'
$utils->cpf->isValid($cpf);   // true
$utils->cpf->generate();      // ex.: '11508890048'

$utils->cnpj->format($cnpj);    // '03.603.568/0001-95'
$utils->cnpj->isValid($cnpj);   // true
$utils->cnpj->generate();       // ex.: '1GJTR3J3XSSA96'

Com agregadores de domínio:

<?php

use Lacus\BrUtils\Cpf\CpfUtils;
use Lacus\BrUtils\Cnpj\CnpjUtils;

$cpf = '11144477735';
$cnpj = '03603568000195';

(new CpfUtils())->format($cpf);      // '111.444.777-35'
(new CnpjUtils())->format($cnpj);    // '03.603.568/0001-95'
(new CpfUtils())->isValid($cpf);     // true
(new CnpjUtils())->isValid($cnpj);   // true

Com helpers funcionais:

<?php

use function Lacus\BrUtils\Cpf\cpf_fmt;
use function Lacus\BrUtils\Cpf\cpf_val;
use function Lacus\BrUtils\Cnpj\cnpj_fmt;
use function Lacus\BrUtils\Cnpj\cnpj_val;

$cpf = '11144477735';
$cnpj = '03603568000195';

cpf_fmt($cpf);     // '111.444.777-35'
cpf_val($cpf);     // true
cnpj_fmt($cnpj);   // '03.603.568/0001-95'
cnpj_val($cnpj);   // true

Uso

Você pode trabalhar de quatro formas equivalentes:

BrUtils — instância única com padrões compartilhados entre os domínios CPF e CNPJ.
Agregadores de domínio — CpfUtils e CnpjUtils diretamente (mesmas classes usadas internamente por BrUtils).
Classes de componente — CpfFormatter, CnpjGenerator e assim por diante.
Helpers funcionais — cpf_fmt(), cnpj_gen() e funções relacionadas para chamadas pontuais.

Todas as abordagens expõem as mesmas opções e comportamento dentro de cada domínio. Para tabelas completas de opções e detalhes por componente, consulte o README de cada pacote empacotado.

`BrUtils`

__construct: new BrUtils($cpf = [], $cnpj = [])

Cada argumento $cpf / $cnpj pode ser uma instância CpfUtils / CnpjUtils já construída ou um array de configuração repassado ao construtor do utils correspondente. Dentro desse array, cada chave de recurso (formatter, generator e validator para CNPJ) aceita um objeto de opções ou um array associativo de valores.

Exemplo: new BrUtils(cpf: ['formatter' => ['hidden' => true]], cnpj: ['validator' => ['type' => CnpjValidationType::Numeric]]).
$cpf, $cnpj: Acesso estilo propriedade às instâncias de utils de domínio (CpfUtils e CnpjUtils).
getCpfUtils(), getCnpjUtils(): Retornam as instâncias internas de domínio para uso direto.

<?php

use Lacus\BrUtils;
use Lacus\BrUtils\Cnpj\Enums\CnpjType as CnpjGenerationType;
use Lacus\BrUtils\Cnpj\Enums\CnpjValidationType;

$utils = new BrUtils();

$utils->cpf->format('11144477735');    // '111.444.777-35'
$utils->cpf->isValid('11144477735');   // true
$utils->cpf->generate();               // ex.: '11508890048'

$utils->cnpj->format('03603568000195');    // '03.603.568/0001-95'
$utils->cnpj->format('12ABC34500DE99');    // '12.ABC.345/00DE-99'
$utils->cnpj->isValid('1QB5UKALPYFP59');   // true
$utils->cnpj->generate(format: true);      // ex.: 'V1.J0V.8WE/DVZ7-50'
$utils->cnpj->generate(                    // ex.: '15381773354961'
    type: CnpjGenerationType::Numeric,
);

Padrões de instância e sobrescrita por chamada

$utils = new BrUtils(
    cpf: [
        'formatter' => ['hidden' => true, 'hiddenKey' => '#'],
        'generator' => ['format' => true],
    ],
    cnpj: [
        'formatter' => ['hidden' => true, 'hiddenKey' => '#'],
        'generator' => ['format' => true],
        'validator' => ['type' => CnpjValidationType::Numeric],
    ],
);

$cpf = '11144477735';
$cnpj = '03603568000195';

$utils->cpf->format($cpf);                  // '111.###.###-##'
$utils->cpf->format($cpf, hidden: false);   // '111.444.777-35'
$utils->cpf->generate(format: false);       // ex.: '58450042259'

$utils->cnpj->format($cnpj);                  // '03.603.###/####-##'
$utils->cnpj->format($cnpj, hidden: false);   // '03.603.568/0001-95'
$utils->cnpj->isValid('1QB5UKALPYFP59');      // false
$utils->cnpj->isValid(                        // true
    '1QB5UKALPYFP59',
    type: CnpjValidationType::Alphanumeric,
);

Passar uma instância CnpjFormatterOptions, CnpjGeneratorOptions ou CnpjValidatorOptions ao construtor de BrUtils armazena esse objeto por referência — mutá-lo depois afeta chamadas subsequentes sem sobrescrita por chamada.

Operações de CPF

Os métodos de CPF são acessados via $utils->cpf, CpfUtils ou os helpers cpf_*(). CPF usa a API v1 de lacus/cpf-utils: entrada apenas string, opções posicionais/nomeadas de formatador e gerador, e sem configurações de validador.

Formatação (`format` / `cpf_fmt`)

Parâmetro	Tipo	Padrão	Descrição
`escape`	`?bool`	`false`	Quando `true`, escapa HTML na string final
`hidden`	`?bool`	`false`	Quando `true`, substitui o intervalo inclusivo `[hiddenStart, hiddenEnd]` na string normalizada de 11 dígitos antes da pontuação
`hiddenKey`	`?string`	`'*'`	Substituição para cada posição oculta
`hiddenStart`	`?int`	`3`	Índice inicial `0`–`10` (inclusivo)
`hiddenEnd`	`?int`	`10`	Índice final `0`–`10` (inclusivo)
`dotKey`	`?string`	`'.'`	Separador entre grupos de dígitos
`dashKey`	`?string`	`'-'`	Separador antes dos dois últimos dígitos
`onFail`	`?\Closure`	veja abaixo	`Closure(mixed $value, Exception $e): string` — usado quando o comprimento sanitizado ≠ 11

O onFail padrão retorna a entrada original sem alteração. Comprimento inválido não lança exceção em format().

$cpf = '11144477735';

$utils->cpf->format($cpf);                                        // '111.444.777-35'
$utils->cpf->format($cpf, hidden: true, hiddenKey: '#');          // '111.###.###-##'
$utils->cpf->format($cpf, dotKey: '', dashKey: '_');             // '111444777_35'

cpf_fmt($cpf, hidden: true);                                       // '111.***.***-**'

Geração (`generate` / `cpf_gen`)

Parâmetro	Tipo	Padrão	Descrição
`format`	`?bool`	`false`	Quando `true`, retorna CPF formatado (`000.000.000-00`); caso contrário, saída compacta de 11 dígitos
`prefix`	`?string`	`''`	Semente base para geração. Caracteres não numéricos são removidos; apenas os primeiros 9 dígitos (índices `0`–`8`) são usados

$utils->cpf->generate();                      // ex.: '11508890048'
$utils->cpf->generate(format: true);          // ex.: '661.134.831-00'
$utils->cpf->generate(prefix: '123456789');   // '12345678909'
cpf_gen(prefix: '123456789', format: true);   // '123.456.789-09'

Validação (`isValid` / `cpf_val`)

Aceita strings de CPF formatadas ou não. Retorna true ou false sem lançar exceção para CPF inválido.

$utils->cpf->isValid('11144477735');      // true
$utils->cpf->isValid('111.444.777-35');   // true
$utils->cpf->isValid('11144477736');      // false
cpf_val('11144477735');                   // true

Operações de CNPJ

Os métodos de CNPJ são acessados via $utils->cnpj, CnpjUtils ou os helpers cnpj_*(). CNPJ usa a API v2 de lacus/cnpj-utils.

Formatação (`format` / `cnpj_fmt`)

Suporta as mesmas opções de lacus/cnpj-fmt. A entrada aceita string ou list<string>.

Parâmetro	Tipo	Padrão	Descrição
`hidden`	`?bool`	`false`	Quando `true`, substitui o intervalo inclusivo `[hiddenStart, hiddenEnd]` na string normalizada de 14 caracteres antes da pontuação
`hiddenKey`	`?string`	`'*'`	Substituição para cada posição oculta (pode ser multi-caractere ou vazia); não pode usar caracteres proibidos
`hiddenStart`	`?int`	`5`	Índice inicial `0`–`13` (inclusivo)
`hiddenEnd`	`?int`	`13`	Índice final `0`–`13` (inclusivo); se `hiddenStart > hiddenEnd`, os valores são trocados
`dotKey`	`?string`	`'.'`	Separador entre grupos `XX` / `XXX` / `XXX`
`slashKey`	`?string`	`'/'`	Separador antes do bloco da filial
`dashKey`	`?string`	`'-'`	Separador antes dos dois últimos caracteres
`escape`	`?bool`	`false`	Quando `true`, escapa HTML na string final
`encode`	`?bool`	`false`	Quando `true`, codifica a string final para URL
`onFail`	`?\Closure`	veja abaixo	`Closure(mixed $value, CnpjFormatterException $e): string` — usado quando o comprimento sanitizado ≠ 14

O onFail padrão retorna string vazia. Tipos de entrada incorretos lançam CnpjFormatterInputTypeError.

$cnpj = '03603568000195';

$utils->cnpj->format($cnpj);              // '03.603.568/0001-95'
$utils->cnpj->format('12ABC34500DE99');   // '12.ABC.345/00DE-99'
$utils->cnpj->format(                     // '03.603.###/####-##'
    $cnpj,
    hidden: true,
    hiddenKey: '#',
);
$utils->cnpj->format(                     // '03603568|0001_95'
    $cnpj,
    dotKey: '',
    slashKey: '|',
    dashKey: '_',
);

cnpj_fmt($cnpj);   // '03.603.568/0001-95'

Geração (`generate` / `cnpj_gen`)

Suporta as mesmas opções de lacus/cnpj-gen.

Parâmetro	Tipo	Padrão	Descrição
`format`	`?bool`	`false`	Quando `true`, retorna CNPJ formatado (`XX.XXX.XXX/XXXX-XX`); caso contrário, saída compacta de 14 caracteres
`prefix`	`?string`	`''`	Semente base para geração. Caracteres não alfanuméricos são removidos, letras são maiúsculas, e apenas os primeiros 12 caracteres (índices `0`–`11`) são usados; caracteres no índice `12+` são ignorados
`type`	`CnpjGenerationType\|'alphanumeric'\|'alphabetic'\|'numeric'\|null`	`CnpjGenerationType::Alphanumeric`	Família de caracteres usada nas posições base geradas

Regras de validação de prefix:

base ID 00000000 é rejeitado (quando os primeiros 8 caracteres estão presentes)
filial ID 0000 é rejeitado (quando os caracteres 9–12 estão presentes)
12 dígitos numéricos repetidos são rejeitados (ex.: 111111111111)

$utils->cnpj->generate();               // ex.: '1GJTR3J3XSSA96'
$utils->cnpj->generate(format: true);   // ex.: 'V1.J0V.8WE/DVZ7-50'
$utils->cnpj->generate(                 // ex.: '12345678855883'
    prefix: '12345678',
    type: CnpjGenerationType::Numeric,
);

Validação (`isValid` / `cnpj_val`)

Suporta as mesmas opções de lacus/cnpj-val. A entrada aceita string ou list<string>.

Parâmetro	Tipo	Padrão	Descrição
`type`	`CnpjValidationType\|'alphanumeric'\|'numeric'\|null`	`CnpjValidationType::Alphanumeric`	Conjunto de caracteres após sanitização
`caseSensitive`	`?bool`	`true`	Quando `false`, letras minúsculas são convertidas para maiúsculas antes da validação alfanumérica

$utils->cnpj->isValid('98765432000198');   // true
$utils->cnpj->isValid('98765432000199');   // false
$utils->cnpj->isValid('1QB5UKALPYFP59');   // true
$utils->cnpj->isValid('1QB5UKALpyfp59');   // false
$utils->cnpj->isValid(                     // true
    '1QB5UKALpyfp59',
    caseSensitive: false,
);
$utils->cnpj->isValid(                     // false
    '1QB5UKALPYFP59',
    type: CnpjValidationType::Numeric,
);

cnpj_val('98765432000198');                         // true
cnpj_val('1QB5UKALpyfp59', caseSensitive: false);   // true
cnpj_val(                                           // false
    '1QB5UKALPYFP59',
    type: CnpjValidationType::Numeric,
);

CNPJ inválido retorna false sem lançar exceção. Tipos de entrada incorretos lançam CnpjValidatorInputTypeError.

Agregadores de domínio (isolados)

Use CpfUtils ou CnpjUtils diretamente quando precisar de apenas um domínio:

<?php

use Lacus\BrUtils\Cpf\CpfUtils;
use Lacus\BrUtils\Cnpj\CnpjUtils;
use Lacus\BrUtils\Cnpj\Enums\CnpjValidationType;

$cpfUtils = new CpfUtils(
    formatter: ['hidden' => true],
    generator: ['format' => true],
);

$cnpjUtils = new CnpjUtils(
    formatter: ['hidden' => true],
    generator: ['format' => true],
    validator: ['type' => CnpjValidationType::Numeric],
);

$cpfUtils->format('11144477735');       // '111.***.***-**'
$cnpjUtils->format('03603568000195');   // '03.603.***/****-**'

Acesso aos componentes

Cada agregador de domínio expõe formatador, gerador e validador internos:

$utils = new BrUtils();

$utils->cpf->getFormatter()->format(                   // '111.***.***-**'
    '11144477735',
    hidden: true,
);
$utils->cpf->getGenerator()->generate(format: true);   // ex.: '545.507.690-68'
$utils->cpf->getValidator()->isValid('11144477735');   // true

$utils->cnpj->getFormatter()->format('12ABC34500DE99');    // '12.ABC.345/00DE-99'
$utils->cnpj->getGenerator()->generate(format: true);      // ex.: '8O.BE5.2KL/UI0Y-06'
$utils->cnpj->getValidator()->isValid('03603568000195');   // true

Use getCpfUtils() / getCnpjUtils() em BrUtils, ou os getters de componente em cada instância de utils de domínio, quando já tiver uma instância configurada e quiser o componente subjacente sem criar um novo.

Misturando estilos

Use BrUtils onde uma configuração compartilhada ajuda, e componentes ou helpers isolados em outros pontos — são as mesmas classes subjacentes:

<?php

use Lacus\BrUtils;
use Lacus\BrUtils\Cnpj\CnpjFormatter;
use Lacus\BrUtils\Cnpj\Enums\CnpjValidationType;

use function Lacus\BrUtils\Cpf\cpf_fmt;
use function Lacus\BrUtils\Cnpj\cnpj_val;

$utils = new BrUtils(cnpj: ['validator' => ['type' => CnpjValidationType::Numeric]]);

// Via fachada
$utils->cpf->format('11144477735');   // '111.444.777-35'

// Via componente retornado pela fachada
$utils->cnpj->getFormatter()->format('12ABC34500DE99');   // '12.ABC.345/00DE-99'

// Via instância de componente separada
(new CnpjFormatter())->format('03603568000195');   // '03.603.568/0001-95'

// Via helpers funcionais
cpf_fmt('11144477735');           // '111.444.777-35'
cnpj_val('98.765.432/0001-98');   // true

Erros e exceções

BrUtils não define tipos de exceção próprios; propaga erros dos pacotes empacotados:

Formatação / geração de CPF: InvalidArgumentException para tipos ou valores de opção inválidos (ex.: hiddenStart fora do intervalo, prefixo com mais de 9 dígitos).
Formatação de CNPJ: CnpjFormatterInputTypeError, CnpjFormatterOptionsTypeError, CnpjFormatterOptionsHiddenRangeInvalidException, CnpjFormatterOptionsForbiddenKeyCharacterException e classes relacionadas.
Geração de CNPJ: CnpjGeneratorOptionsTypeError, CnpjGeneratorOptionPrefixInvalidException, CnpjGeneratorOptionTypeInvalidException e classes relacionadas.
Validação de CNPJ: CnpjValidatorInputTypeError, CnpjValidatorOptionsTypeError, CnpjValidatorOptionTypeInvalidException e classes relacionadas.

Tipos de opção inválidos em CNPJ são subclasses de TypeError; valores de opção inválidos são subclasses de Exception. Falhas de validação de CPF e CNPJ retornam false. Falha de comprimento na formatação de CPF é tratada por onFail (padrão: retorna a entrada); falha de comprimento na formatação de CNPJ usa onFail (padrão: retorna '').

<?php

use Lacus\BrUtils;
use Lacus\BrUtils\Cnpj\Exceptions\CnpjFormatterInputTypeError;
use Lacus\BrUtils\Cnpj\Exceptions\CnpjValidatorInputTypeError;

$brUtils = new BrUtils();

try {
    $brUtils->cnpj->format(12345);   // lança CnpjFormatterInputTypeError
} catch (CnpjFormatterInputTypeError $e) {
    echo $e->getMessage();
}

try {
    $brUtils->cnpj->isValid(12345678000198);   // lança CnpjValidatorInputTypeError
} catch (CnpjValidatorInputTypeError $e) {
    echo $e->getMessage();
}

$cpfOut = $brUtils->cpf->format(     // 'invalid'
    'short',
    onFail: static fn ($value) => 'invalid'
);
$cnpjOut = $brUtils->cnpj->format(   // 'invalid'
    'short',
    onFail: static fn () => 'invalid',
);

Para listas completas de exceções e comportamento em casos extremos, consulte o README de cada pacote empacotado.

Pacotes empacotados

Pacote	Principais recursos	README
`lacus/cpf-utils`	`CpfUtils`, `CpfFormatter`, `CpfGenerator`, `CpfValidator`, `cpf_fmt()`, `cpf_gen()`, `cpf_val()`	docs
`lacus/cnpj-utils`	`CnpjUtils`, `CnpjFormatter`, `CnpjGenerator`, `CnpjValidator`, `CnpjType`, `CnpjValidationType`, `cnpj_fmt()`, `cnpj_gen()`, `cnpj_val()`	docs

Todos os símbolos de CPF estão disponíveis em Lacus\BrUtils\Cpf\; todos os de CNPJ em Lacus\BrUtils\Cnpj\. Demos interativas: CPF e CNPJ.

API

BrUtils: Fachada de alto nível com acesso $cpf / $cnpj e getCpfUtils() / getCnpjUtils()
CpfUtils: Agregador de domínio para formatar, gerar e validar CPF
CnpjUtils: Agregador de domínio para formatar, gerar e validar CNPJ
CpfFormatter, CpfFormatterOptions, CpfGenerator, CpfGeneratorOptions, CpfValidator: Classes de componente de CPF
CnpjFormatter, CnpjFormatterOptions, CnpjGenerator, CnpjGeneratorOptions, CnpjValidator, CnpjValidatorOptions: Classes de componente de CNPJ
CnpjGenerationType, CnpjValidationType: Enums de geração e validação de CNPJ
cpf_fmt(), cpf_gen(), cpf_val(): Helpers funcionais de CPF (Lacus\BrUtils\Cpf\)
cnpj_fmt(), cnpj_gen(), cnpj_val(): Helpers funcionais de CNPJ (Lacus\BrUtils\Cnpj\)
Exceções: CPF — InvalidArgumentException para opções inválidas; CNPJ — hierarquias completas de TypeError / Exception dos pacotes empacotados (veja READMEs vinculados)

Contribuição e Suporte

Agradecemos contribuições! Consulte nossas Diretrizes de Contribuição para detalhes. Se este projeto for útil para você, considere:

⭐ Dar uma estrela no repositório
🤝 Contribuir com o código
💡 Sugerir novos recursos
🐛 Reportar bugs

Licença

Este projeto está licenciado sob a MIT License — consulte o arquivo LICENSE para detalhes.

Changelog

Consulte o CHANGELOG para a lista de alterações e histórico de versões.

Made with ❤️ by Lacus Solutions

Recursos​

Instalação​

Importação​

Início rápido​

Uso​

BrUtils​

Padrões de instância e sobrescrita por chamada​

Operações de CPF​

Formatação (format / cpf_fmt)​

Geração (generate / cpf_gen)​

Validação (isValid / cpf_val)​

Operações de CNPJ​

Formatação (format / cnpj_fmt)​

Geração (generate / cnpj_gen)​

Validação (isValid / cnpj_val)​

Agregadores de domínio (isolados)​

Acesso aos componentes​

Misturando estilos​

Erros e exceções​

Pacotes empacotados​

API​

Contribuição e Suporte​

Licença​

Changelog​