README

An elegant, Laravel-first toolkit for validating, formatting, sanitizing, and generating Brazilian documents.

Includes CPF, CNPJ, CEP, CNH, PIS/PASEP, CNS, and Título de eleitor. Current version: 1.4.0 (see VERSION). The architecture is prepared for future document types.

Author: Lucas Cavalheri · GitHub · LinkedIn

Install via Composer: packagist.org/packages/cavalheri/laravel-brazil-documents

Requirements

PHP 8.3+
Laravel 13.x

Documentation

Hosted on Vercel:

pt-BR (default): laravel-brazil-documents.lucascavalheri.com.br
English: /en/

Local preview:

npm install
npm run dev

Changelog

See CHANGELOG.md for release notes.

Installation

Published on Packagist:

composer require cavalheri/laravel-brazil-documents

The package supports Laravel auto-discovery. No manual registration is required.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=brazil-documents-config

return [
    'helpers' => true,
    'locale' => null,
];

helpers — Registers global cpf(), cnpj(), cep(), cnh(), pis(), cns(), and tituloEleitor() helpers when true.
locale — Overrides the locale used for validation messages. When null, Laravel's current locale is used.

Quick Start

Facade

use Cavalheri\LaravelBrazilDocuments\Facades\BrazilDocuments;

BrazilDocuments::cpf('12345678909')->isValid();
BrazilDocuments::cpf('12345678909')->format();
BrazilDocuments::cpf('123.456.789-09')->sanitize();
BrazilDocuments::cpf()->generate();

BrazilDocuments::cnpj('11222333000181')->isValid();
BrazilDocuments::cep('01001000')->format();
BrazilDocuments::cnh('12345678900')->isValid();
BrazilDocuments::cnh()->generate();

BrazilDocuments::pis('12056413177')->isValid();
BrazilDocuments::pis('12056413177')->format();

BrazilDocuments::cns('279802393660003')->isValid();
BrazilDocuments::cns('279802393660003')->format();

BrazilDocuments::tituloEleitor('825169091279')->isValid();
BrazilDocuments::tituloEleitor('825169091279')->format();

Support classes

use Cavalheri\LaravelBrazilDocuments\Support\Cpf;
use Cavalheri\LaravelBrazilDocuments\Support\Cnpj;
use Cavalheri\LaravelBrazilDocuments\Support\Cep;
use Cavalheri\LaravelBrazilDocuments\Support\Cnh;
use Cavalheri\LaravelBrazilDocuments\Support\Pis;
use Cavalheri\LaravelBrazilDocuments\Support\Cns;
use Cavalheri\LaravelBrazilDocuments\Support\TituloEleitor;

Cpf::isValid('12345678909');
Cpf::format('12345678909');
Cpf::sanitize('123.456.789-09');
Cpf::generate();

Value objects

use Cavalheri\LaravelBrazilDocuments\ValueObjects\CpfValue;

CpfValue::from('12345678909')->formatted();
CpfValue::from('123.456.789-09')->sanitized();
CpfValue::from('12345678909')->isValid();

Validation rules

use Cavalheri\LaravelBrazilDocuments\Rules\Cpf;
use Cavalheri\LaravelBrazilDocuments\Rules\Cnpj;
use Cavalheri\LaravelBrazilDocuments\Rules\Cep;
use Cavalheri\LaravelBrazilDocuments\Rules\Cnh;
use Cavalheri\LaravelBrazilDocuments\Rules\Pis;
use Cavalheri\LaravelBrazilDocuments\Rules\Cns;
use Cavalheri\LaravelBrazilDocuments\Rules\TituloEleitor;

$request->validate([
    'cpf' => ['required', new Cpf],
    'cnpj' => ['required', new Cnpj],
    'cep' => ['required', new Cep],
    'cnh' => ['required', new Cnh],
    'pis' => ['required', new Pis],
    'cns' => ['required', new Cns],
    'titulo_eleitor' => ['required', new TituloEleitor],
]);

Helpers

When enabled in config:

cpf('12345678909')->format();
cnpj('11222333000181')->format();
cep('01001000')->format();
cnh('12345678900')->format();
pis('12056413177')->format();
cns('279802393660003')->format();
tituloEleitor('825169091279')->format();

Localization

Validation messages are available in English (default) and Portuguese (pt_BR).

Publish translations:

php artisan vendor:publish --tag=brazil-documents-lang

Switch locale at runtime:

app()->setLocale('pt_BR');

Or override via config:

'locale' => 'pt_BR',

Validation behavior

CPF and CNPJ use official check-digit algorithms.
Repeated sequences (e.g. 11111111111, 00000000000) are rejected.
CEP must contain exactly 8 numeric digits.

Testing

composer test

With coverage:

composer test:coverage

Project structure

config/brazil-documents.php
resources/lang/en/validation.php
resources/lang/pt_BR/validation.php
src/
├── Concerns/
├── Contracts/
├── Exceptions/
├── Facades/
├── Helpers/
├── Rules/
├── Services/
│   └── Documents/
├── Support/
├── ValueObjects/
└── LaravelBrazilDocumentsServiceProvider.php
tests/
├── Feature/
└── Unit/

Roadmap

Planned document types for future releases:

State registration (Inscrição Estadual)
PIX keys
Boleto validation

Contributing

Contributions are welcome. Please open an issue before large changes, and ensure tests pass:

composer test

Follow PSR-12 and keep the public API consistent with existing document handlers.

For AI-assisted development, see AGENTS.md and CLAUDE.md. Cursor rules live in .cursor/rules/.

See SECURITY.md to report vulnerabilities privately.

License

The MIT License (MIT). See LICENSE for details.

cavalheri / laravel-brazil-documents

Maintainers

Package info

Statistics

Security