Product Decisions This Supports
- Brazil market entry / localization roadmap. This package supplies Filament form fields pre-built for pt-BR conventions (CPF/CNPJ, CEP/postal code, phone, currency and similar masked inputs). The build-vs-buy decision is effectively made: adopting it removes a localization workstream from the roadmap rather than adding one.
- Build vs buy for input masking and document validation. Hand-rolling CPF/CNPJ check-digit validation, masking, and CEP formatting is deceptively fiddly and easy to get subtly wrong. Buying (adopting) is the right call for any team that does not treat Brazilian document validation as core IP.
- Admin/internal tooling velocity. Because it is a Filament plugin, it plugs directly into existing Filament resources. If the product already runs Filament for back-office, ops, support, or KYC review screens, this is near-zero integration cost and speeds up internal tool delivery ahead of customer-facing work.
- Feature-level use cases to scope against: checkout and billing address forms, customer onboarding/KYC, CRM and lead capture, invoicing with CNPJ, healthcare and insurance registration — anywhere a Brazilian end user types an identity or address document.
- Version 5.0.1 specifically improves the upgrade-path decision. Dropping the
illuminate/contracts dependency and adding Laravel 13.x compatibility lowers dependency-conflict risk and keeps the package viable across the next framework upgrade cycle. That is a supply-chain and maintainability signal, not a feature signal — it means "safe to standardize on" rather than "new capability to plan around."
When to Consider This Package
Adopt when all of the following hold:
- The application is built on Filament. This is the single hardest gate — the package is a Filament field set, not a general Laravel validation library, and delivers almost no value outside a Filament form context.
- The primary or a significant user base is Brazilian, so pt-BR input conventions are a real requirement rather than a nice-to-have.
- You want consistency across many forms — a shared, maintained component set beats per-form masking logic duplicated across resources.
- Your team is small enough that not owning document-validation code is worth more than controlling it.
Look elsewhere or plan mitigations when:
- You are not on Filament. Use a standalone Laravel validation/masking package instead; do not adopt Filament to get this package.
- You need more than input formatting. CEP autocomplete with address fill, full address normalization, or third-party validation services sit outside a form-field package's scope — expect to pair it with an API integration.
- You require vendor support or SLAs. This is a small, effectively single-maintainer open-source package. Treat it as community dependency, not a vendor relationship; if that is unacceptable, budget for a fork or in-house equivalent.
- You are pinned to a Filament or Laravel major that the release does not cover. Verify the compatibility matrix before committing; release 5.0.1 signals active tracking of Laravel 13.x but Filament major alignment should be confirmed explicitly.
- You need deep customization of mask behavior or validation messaging beyond what the fields expose — check extensibility first, or you will end up wrapping it in a way that negates the savings.
How to Pitch It (Stakeholders)
For executives: This is a small, free, open-source component library that shortcuts a required piece of a Brazil launch — the forms where customers enter tax IDs, postal codes, and phone numbers. Without it, we either pay to build and maintain that logic ourselves or ship forms that accept malformed Brazilian data, which shows up as failed checkouts, rejected KYC submissions, and support tickets. Cost is effectively zero and integration effort is low. The newest patch (5.0.1) is maintenance-only: dependency updates plus explicit Laravel 13.x compatibility, which means it stays viable through our next framework upgrade rather than becoming a liability. The main caveat to flag honestly is that it is community-maintained by a very small number of contributors with no support contract — a low but real continuity risk that we manage by pinning versions and keeping the integration thin enough to replace.
For engineering: It is a Filament field package for pt-BR formatted inputs, so adoption is gated on us running Filament for the relevant screens. Integration is a composer require plus using the field classes in resources — no service provider gymnastics or data-model changes. The 5.0.1 diff is patch-level and low-risk: Dependabot bumps, removal of the illuminate/contracts dependency (reduces conflict surface and transitive coupling), and added Laravel 13.x compatibility. No breaking API changes or deprecations are indicated, so upgrading from 5.0.0 should be routine — but as with any dependency removal, run the full suite and confirm nothing was implicitly relying on illuminate/contracts through this package. Recommended posture: pin to a tested minor, keep usage confined to form-layer code with no business logic woven into the fields, and confirm the Filament major we run is explicitly supported before we standardize on it across resources.