lumensistemas/br-validation

Validators, generators, and formatters for Brazilian identifiers (CPF and CNPJ).

1.0.0 2026-05-05 01:23 UTC

Requires

• php: ^8.3
• ext-mbstring: *

Requires (Dev)

• lumensistemas/lens: ^1.0
• pestphp/pest: ^4.0

MIT

• Lumen Sistemas

• validator
• validation
• cpf
• cnpj
• br
• brazilian

README

Validators, generators, and formatters for Brazilian identifiers (CPF and CNPJ) in PHP. Framework-agnostic and dependency-free at runtime.

Requirements

• PHP 8.3 or newer
• ext-mbstring

Installation

composer require lumensistemas/br-validation

Usage

CPF

use LumenSistemas\BrValidation\Cpf;

Cpf::isValid('856.981.040-77');   // true
Cpf::isValid('85698104077');      // true (raw form also accepted)
Cpf::isValid('11111111111');      // false (all-equal sequence)
Cpf::isValid(85698104077);        // false (non-string input)

Cpf::format('85698104077');       // '856.981.040-77'
Cpf::normalize('856.981.040-77'); // '85698104077'

Cpf::generate(); // a valid 11-digit CPF

CNPJ

use LumenSistemas\BrValidation\Cnpj;

Cnpj::isValid('11.222.333/0001-81');      // true (legacy numeric)
Cnpj::isValid('12ABC34501DE35');          // true (alphanumeric, 2026 rules)
Cnpj::isValid('12abc34501de35');          // true (case-insensitive)
Cnpj::isValid('00000000000000');          // false (all-equal sequence)

Cnpj::format('11222333000181');           // '11.222.333/0001-81'
Cnpj::format('12abc34501de35');           // '12.ABC.345/01DE-35'
Cnpj::normalize(' 11.222.333/0001-81 '); // '11222333000181'

Cnpj::generateNumeric();      // a valid 14-digit numeric CNPJ
Cnpj::generateAlphanumeric(); // a valid alphanumeric CNPJ

Behavior

• Validation never throws. isValid accepts any input type and returns false for non-string or malformed values. Callers can pass user input directly without try/catch.
• All-equal sequences are rejected (11111111111, 00000000000000, …) even though they pass the mod-11 algorithm. They are conventional placeholder values across the Brazilian validation ecosystem and never represent real identifiers.
• CNPJ is case-insensitive. Letters in alphanumeric CNPJs are normalized to uppercase before validation and formatting; both '12abc34501de35' and '12ABC34501DE35' validate equivalently, and format always produces the canonical uppercase masked form.
• Numeric CNPJs remain valid in perpetuity alongside the 2026 alphanumeric format. This is an accept-both library, not a transitional one.
• format() is tolerant. When the input shape doesn't match the canonical form, format() returns the input unchanged rather than raising. It does not validate check digits — that is isValid()'s job.

Laravel integration

A companion package lumensistemas/laravel-br-validation is planned, providing Rule classes and a service provider. It will be linked here once published.

Development

composer install
composer test

License

MIT. See LICENSE.