pt-br-validator adds Brazilian document rules to Laravel validation

The package is a Laravel extension, not a framework of its own

The scope is narrow and the README is upfront about it. This is a library that adds Brazilian format validations to Laravel, covering CPF, CNPJ, vehicle plate, CEP, telephone, mobile phone and similar values. There is no client library, no HTTP layer and no configuration format of its own to learn. The repository layout is what you would expect for a Laravel package: composer.json, phpunit.xml, a src/ directory holding the implementation, a tests/ directory, and .travis.yml as the continuous integration descriptor. The extension point is the framework validator itself, so the rules read like every other rule you already write, using the pipe separated string syntax, and a rule that the framework does not recognise becomes one it recognises once the package is installed. For a team building a Brazilian product, that is the whole value proposition in a sentence.

Installation is a single composer require, with an old provider caveat

The README describes the install as two steps. You move to your project directory, for example a path like /etc/www/projeto, and then run the Composer install for this package.

cd /etc/www/projeto

composer require laravellegends/pt-br-validator

There is one version caveat and it is easy to miss. If you are using a version of the library earlier than 5.2, you have to register the provider in config/app.php yourself.

'providers' => [
    // ... outros pacotes
    LaravelLegends\PtBrValidator\ValidatorProvider::class
]

From 5.2 onward the package presumably relies on the framework own package discovery, but the README only says the provider step applies to versions before 5.2 and then says that to use the validation you just follow the standard Laravel procedure. If you are on a recent release this does not apply to you. If you are maintaining an older application, you need that provider block.

Sixteen rules cover identifiers, masks and phone formats

The rule table is the substance of the package, and it splits into three families. The identifier rules check validity rather than appearance: cnpj, cpf, cns, pis and cpf_ou_cnpj, which accepts either a CPF or a CNPJ. The mask rules check formatting only: formato_cnpj expects 99.999.999/9999-99, formato_cpf expects 999.999.999-99, formato_cep accepts 99999-999 or 99.999-999, telefone expects 9999-9999, telefone_com_ddd expects (99)9999-9999, telefone_com_codigo expects +55(99)9999-9999, and formato_placa_de_veiculo validates a vehicle plate including the MERCOSUL pattern. The mobile rules are celular, celular_com_ddd with the parenthesised area code, and celular_com_codigo in the +99(99)99999-9999 form. There is also uf, which checks a value against a valid Brazilian state abbreviation. The distinction between an identifier rule and a mask rule is worth keeping straight, because they answer different questions and the README names them separately.

Validation runs through the standard Validator::make call

The README shows a minimal test that uses the standard facade.

$validator = \Validator::make(
    ['telefone' => '(77)9999-3333'],
    ['telefone' => 'required|telefone_com_ddd']
);

dd($validator->fails());

The same rules apply when you validate through an Illuminate request instance, using the validate method, and the README gives a route example for that.

use Illuminate\Http\Request;

// URL: /testando?telefone=3455-1222

Route::get('testando', function (Request $request) {

    try{

        $dados = $request->validate([
            'telefone' => 'required|telefone',
            // outras validações aqui
        ]);

    } catch (\Illuminate\Validation\ValidationException $e) {
        dd($e->errors());
    }

});

Both examples use dd to inspect the result, which is fine for a scratch test and wrong for production code. The important part is that no service class or separate API appears anywhere in the flow.

Messages can be overridden per rule or per request

Every rule listed comes with default validation messages, and the README shows two ways to change them. The first is the third parameter of the make call on the validator, which takes an array whose keys are the validation names and whose values are the messages.

Validator::make($valor, $regras, ['celular_com_ddd' => 'O campo :attribute não é um celular'])

The second is the messages method on a Form Request class created with the php artisan make:request command.

public function messages() {

    return [
        'campo.telefone' => 'Telefone não válido!'
    ];
}

The messages you write are in Portuguese, which is consistent with a package aimed at Brazilian developers. Note that the attribute placeholder is used in the inline form, so the framework can still name the field for the user. The two mechanisms coexist, and the Form Request approach is the one that scales when the same rule appears in several forms.

The rules are also available as standalone classes

If you need one rule outside a validator call, the README points to the underlying classes, listed under the Rules namespace.

\LaravelLegends\PtBrValidator\Rules\Celular::class
\LaravelLegends\PtBrValidator\Rules\CelularComDdd::class
\LaravelLegends\PtBrValidator\Rules\CelularComCodigo::class
\LaravelLegends\PtBrValidator\Rules\Cnh::class
\LaravelLegends\PtBrValidator\Rules\Cnpj::class
\LaravelLegends\PtBrValidator\Rules\Cpf::class
\LaravelLegends\PtBrValidator\Rules\Cns::class
\LaravelLegends\PtBrValidator\Rules\FormatoCnpj::class

The listing in the README is truncated partway through, so the full set of class names is not visible there, but the pattern is clear: one class per rule, named after the rule it implements. This is the escape hatch for cases the string syntax does not cover, such as validating a value outside a request, or reusing the check in a console command or a queued job. Note that Cnh appears in the class list even though it is not in the rule table shown above, which suggests the table in the README is not exhaustive.

Version compatibility is a matrix you must check before upgrading

The README publishes a compatibility table pairing framework versions with library versions, and it is the thing to look at first. Laravel 4.* pairs with library 4.*, Laravel 5.* pairs with 5.1.*, Laravel ^6.0 || ^7.0 || ^8.0 pairs with ^8.0, and then each later Laravel major has a matching library major: ^9.0 with ^9.0, ^10.0 with ^10.0, ^11.0 with ^11.0, ^12.0 with ^12.0, and ^13.0 with ^13.0. The releases follow the same cadence. Version 12.1.0 and 12.2.0 were both published on 2025-06-21, 13.0.0 came on 2026-05-12, and the last push was on 2026-05-12 as well. The library therefore follows the framework major version numbering rather than versioning independently, which means an application upgrading to a new Laravel major needs the matching library release, and a project pinned to an older major is pinned to an older library. That is a reasonable design, but it also means the package cannot be updated independently of the framework.

Structure validation is not the same as verifying a real registration

There is one limitation the README does not spell out but its own wording implies. Rules such as cnpj and cpf validate whether the field is a valid CNPJ or CPF, and the documentation helpfully points you to third party generator sites, geradorcnpj.com, geradordecpf.org and geradornv.com.br for the CNS, so you can produce values that pass the check. That is a deliberate convenience for test fixtures, and it also tells you what the rule does: it checks the digit structure and check digits of the identifier, not whether the number is registered with a government authority, not whether the holder exists, and not whether it has been cancelled. The same applies to pis and to cns, the health registry number. If your application needs to know that a document actually belongs to a person, no validation rule in this package can answer that, and the failure mode is a form that accepts well formed but invented numbers.

Editorial conclusion

Adopt pt-br-validator when your Laravel application accepts Brazilian tax identifiers, health registry numbers or local phone formats and you want those checks expressed as ordinary validation rules rather than custom service calls. Do not adopt it if your inputs are international, since the rules are specific to Brazilian formats by design, and do not assume the package verifies that a CNPJ is actually issued, only that it has a valid structure and check digits. Verify first by installing with composer require laravellegends/pt-br-validator on a Laravel version listed in the compatibility table, since version 13.0.0 pairs with Laravel ^13.0, and by confirming in your test suite that the rules you rely on reject the malformed values you care about.

Frequently asked questions

Official sources

1. LaravelLegends/pt-br-validator on GitHub
2. License: MIT
3. Project website
4. README
5. Releases