modulae/ptbr-doc-validator

Brazilian document validators for Laravel.

0.1.1 2026-02-19 14:01 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0||^12.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0

MIT

• João Prado

• laravel
• Modulae
• ptbr-doc-validator

README

A lightweight Laravel package that provides validators and utilities for common Brazilian documents. The first supported document is CNPJ, including support for alphanumeric variants that are to be introduced in June 2026. It includes:

• A cnpj validation rule registered with Laravel's Validator facade.
• A Cnpj value object with helpers to normalize, format, cast in Eloquent models, and validate values.
• A cnpjToString helper to normalize strings and arrays of CNPJ values.
• Localized validation error messages (EN and PT-BR).

Installation

Install via Composer:

composer require modulae/ptbr-doc-validator

Publish translations (optional, if you want to customize messages):

php artisan vendor:publish --tag="ptbr-doc-validator-translations"

Usage

1) Using the built-in cnpj validation rule

use Illuminate\Support\Facades\Validator;

$validator = Validator::make(
    ['cnpj' => 'T6.JSP.XPS/0001-11'],
    ['cnpj' => 'cnpj']
);

$validator->passes(); // true/false

2) Using the Cnpj value object

use Modulae\PTBRDocValidator\ValueObjects\Cnpj;

$cnpj = new Cnpj('T6.JSP.XPS/0001-11');
$cnpj->isValid();     // bool
$cnpj->raw();         // "T6JSPXPS000111"
$cnpj->formatted();   // "T6.JSP.XPS/0001-11"
(string) $cnpj;       // "T6JSPXPS000111"

Eloquent cast example:

class Company extends Model
{
    protected $casts = [
        'cnpj' => \Modulae\PTBRDocValidator\ValueObjects\Cnpj::class,
    ];
}

3) Using the cnpjToString helper

use function Modulae\PTBRDocValidator\cnpjToString;

cnpjToString('T6.JSP.XPS/0001-11');
// => "T6JSPXPS000111"

cnpjToString(['32.332.643/0001-29', 'T6.JSP.XPS/0001-11']);
// => ['32332643000129', 'T6JSPXPS000111']

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.