Download the PHP package leandrocfe/filament-ptbr-form-fields without Composer

Brazilian pt-BR form fields.

This package provides custom form fields for Filament that are commonly used in Brazilian web applications, such as CPF/CNPJ validation, phone number formatting, money with currency symbol, and CEP integration with ViaCep.

This package uses LaravelLegends/pt-br-validator to validate Brazilian Portuguese fields.

Installation

Version 5.1 targets PHP 8.2+, Filament 5, and laravellegends/pt-br-validator ^12.2 || ^13.0. The validator minimum is now 12.2 for alphanumeric CNPJ support; applications pinned to 10.x, 11.x, or 12.0–12.1 must upgrade that dependency before upgrading this package.

You can install the package via Composer:

Filament V2 - if you are using Filament v2.x, you can use this section

Filament V3 - if you are using Filament v3.x, you can use this section

Filament V4 - if you are using Filament v4.x, you can use this section

Usage

CPF / CNPJ

To create a dynamic input that accepts either CPF or CNPJ, use:

If you want to create an input that only accepts CPF or only accepts CNPJ, use:

For dynamic CPF/CNPJ inputs:

alphanumeric: false only restricts the mask. The cpf_ou_cnpj validation rule still accepts an alphanumeric CNPJ that reaches the field from another source (an imported record, a request payload, etc.).

cnpj() also accepts the flag positionally, which is handy when you do not need a custom mask:

You can also use mask constants directly:

If you want to use a custom mask for the input, use the cpf() or cnpj() method with a string argument representing the desired mask:

Uppercase normalization

The alphanumeric CNPJ (Anexo XV of IN RFB nº 2.119/2022) only assigns values to uppercase letters, so Document normalizes the field:

• the input is displayed in uppercase (text-transform: uppercase);
• the state is uppercased before validation and before being dehydrated (saved).

Behavior change: the dehydrated state is now always uppercased, even when dehydrateMask() is not used. A value typed as 12.abc.345/01de-35 is saved as 12.ABC.345/01DE-35 (or 12ABC34501DE35 with dehydrateMask()). While the user is still typing, the live Livewire state keeps the original casing, so a custom afterStateUpdated() callback may receive lowercase characters.

Validation

Document uses LaravelLegends/pt-br-validator to validate Brazilian Portuguese fields by default - cpf_ou_cnpj | cpf | cnpj

You can disable validation using the validation(false) method:

Phone number

To create a dynamic input that formats phone numbers with DDD, use:

If you want to use a custom phone number format, use the `mask() method with a string argument representing the desired format:

Money

To create a money input field, use the following syntax:

The field uses a calculator-style mask: type only digits and the thousands/decimal separators are applied for you. Typing 100020 displays 1.000,20. You do not type . or ,.

When editing an amount in the middle, the caret and selected digit range stay at the same logical digits as the mask adds or removes separators. If Backspace or Delete lands directly on a separator, the adjacent digit is removed while preserving the caret by digit position. Pressing - toggles the sign while retaining the caret or selection. Both operations dispatch a bubbling input event, so wire:model receives the updated value. Readonly and disabled inputs are preserved.

Input compatibility and optional decimal parsing

By default, 5.1 preserves the 5.0.1 input contract: remove . and ,, then read the remaining integer as cents. For example, 1.230 displays 12,30, 1.000 displays 10,00, 10,5 displays 1,05, and an integer 1000 displays 10,00. Empty or null input displays 0,00 and saves zero. intFormat() chooses integer-cent output; it does not change this default input contract.

For persisted decimal units (including database floats), explicitly opt in:

In decimalInput() mode, numeric 1000 and 1000.2 represent units, canonical strings 1000.20 and 1000.2000 represent 1000.2 units, and digit-only strings remain calculator-style cents. With intFormat(), integer numbers and integer strings represent cents. Localized values such as 1.234,50 are supported. Extra fractional digits must be zero: 1000.2001 is rejected at scale 2. Ambiguous BRL strings such as 1.230 are rejected in this opt-in mode; use 1.23 for 1.23 units or 1.230,00 for 1230 units. The explicit .000 convention (1.000) and multiple groups (1.234.567) represent thousands. This convention applies to currencies with . as their thousands separator and a different decimal separator.

Invalid, ambiguous, or overflowing input throws InvalidArgumentException during hydration or dehydration, instead of clearing or saving an altered value. Validate/normalize imported amounts before filling a form. Both opt-ins accept a boolean or closure and can be disabled with false. nullable() alone does not enable emptyAsNull(); blank-to-null behavior is independent of validation.

Integer cents and their formatted masks remain exact throughout the PHP integer range, including values above JavaScript's safe integer limit. The browser mask uses BigInt. The legacy Currency.masking() helper separately retains numeric-unit versus string-cent input semantics, locales, and the options object for Intl.NumberFormat (including minimumFractionDigits / maximumFractionDigits). Current fields use the new mask directly. Ordinary decimal output keeps the legacy float type; amounts whose cents exceed 2^52 return an exact decimal string instead. Use intFormat() with PHP integers or integer strings, or dehydrateMask(), when exact large amounts are required. Do not pass large amounts as floats: their precision is already lost before the field receives them; unsafe or non-finite floats are rejected.

Upgrading subclasses and published assets

Run php artisan filament:assets after upgrading. The asset is now money under leandrocfe/filament-ptbr-form-fields; the previous public/js/money-script.js can be removed. If no published asset exists, the field uses an inline copy of the same mask.

The protected sanitizeState(?string $state): ?int, getOnKeyPress(): array, getOnKeyUp(): array, and getOnBlur(): array extension points remain available and are invoked. sanitizeState() applies to default parsing; opting in to decimalInput() selects the new parser instead. The keyboard hooks now return keydown and input.capture attributes by default; subclasses overriding them may keep their attributes or migrate to those events to support paste, sign changes, and caret preservation.

Using Integer Values

If you prefer to work with integer values, you can format the money input using the intFormat() method:

Getting the Raw State

To retrieve the formatted state of the field, you can use the dehydrateMask() method:

If you need to remove the prefix from the money input, simply pass null to the prefix() method:

Currency Formatting

This package leverages the archtechx/money package under the hood. By default, it uses the BRL (Brazilian Real) format for currency values.

If you want to switch to the USD (United States Dollar) format, you can do so with the following code:

You can also define custom currencies to suit your specific needs:

CEP (Brazilian ZIP Code)

The CEP field provides automatic address lookup through configurable providers like ViaCep and BrasilAPI.

Basic Usage

Configuration

You can publish the configuration file to customize the default API endpoints:

This will publish config/filament-ptbr-form-fields.php:

You can also override the endpoints via environment variables in your .env file:

Note: The protocol (https://), host, and trailing slash (/) are required when specifying custom URLs. If your application uses configuration caching, make sure to run php artisan config:clear (or php artisan config:cache) after modifying environment variables or the configuration file.

Lookup Modes

ON_BLUR (default): Automatically fetches address when the field loses focus

SUFFIX: Shows a search button next to the field

Custom Error Message

Available Providers

• ViaCepProvider: Default provider using ViaCep API
• BrasilApiProvider: Alternative provider using BrasilAPI

Custom Provider

You can create your own provider by implementing CepProviderInterface:

Troubleshooting

URI must include a scheme and host

If you encounter the following exception when searching for a CEP:

This occurs when the provider endpoint URL is missing the scheme (e.g., viacep.com.br/ws/ instead of https://viacep.com.br/ws/).

To resolve this:

1. Ensure your VIACEP_URL or BRASILAPI_URL environment variables in .env include the full protocol: https://viacep.com.br/ws/ or https://brasilapi.com.br/api/cep/v1/.
2. If you have published config/filament-ptbr-form-fields.php, verify that the default URLs include https://.
3. Clear the configuration cache by running:

Legacy Method (Deprecated)

The old viaCep() method is still available for backward compatibility but will be removed:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability within this package, please send an e-mail to [email protected].

Credits

• Leandro Costa Ferreira
• All Contributors

License

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