Filament Ptbr Form Fields Laravel Package

Technical Evaluation

Package overview: leandrocfe/filament-ptbr-form-fields is a Filament plugin supplying Brazil-specific form inputs (CPF/CNPJ, CEP/postal code, phone, currency, and related masks/validation) for Laravel admin panels. It is a UI-layer dependency, not a domain or data-integrity library — its blast radius is limited to form rendering and input masking, which materially lowers integration risk compared with packages that touch persistence, auth, or payment flows.

Architecture fit: The package sits cleanly in the presentation tier as a Filament plugin registered via a panel provider. It does not impose its own models, migrations, service providers with side effects, or config surface that would restructure an application. That makes it a low-coupling, high-substitutability component — field-level wrappers can be replaced with custom Filament components if the package is abandoned.

What changed in 5.0.1: This is a patch release, but not a trivial one. Two substantive items sit alongside routine Dependabot bumps (composer-install 3→4, fetch-metadata 2.5.0→3.1.0, both CI-only and non-runtime):

• Removal of the direct illuminate/contracts dependency.
• Addition of Laravel 13.x compatibility.

The dependency removal is the item requiring diligence. Dropping a direct illuminate/contracts requirement means the package now relies on the host application (or Filament's own constraints) to bring in the relevant Illuminate contracts. In practice this is usually safe because any Laravel app already provides them transitively, but it widens the acceptable dependency envelope and removes a version pin that previously constrained resolution. Composer may now resolve a contracts version the package was never tested against.

Technical risk: Low-to-moderate.

• Low: runtime behavior of the form fields is untouched; no public API, config keys, or component signatures changed in this release.
• Moderate: the widened Laravel version range means the plugin's declared compatibility now extends to a framework major that the maintainer may not exercise in CI. "Adds Laravel 13.x compat" in a patch bump is a compatibility declaration, not evidence of testing. Treat it as an untested claim until the CI matrix is confirmed.
• Low: maintainer is a single primary contributor with Dependabot-driven hygiene; bus factor is the standing structural risk, unchanged by this release.

Key questions:

1. Does CI actually run the test suite against the new Laravel major, or was only the composer.json constraint widened?
2. What is the declared php and filament/filament constraint range after PR #76, and does it overlap our pinned versions?
3. Was illuminate/contracts removed because it is genuinely redundant, or to unblock resolution — and does the lockfile still contain a compatible version?
4. Is Filament v4/v5 support in scope for 5.0.x, or does our Filament version require a different major line of this plugin?
5. What is the fallback if the plugin goes unmaintained — how many fields do we actually consume?

Integration Approach

Stack fit: Compatible with any Laravel + Filament application. Because the plugin is presentation-only, it composes with existing Filament panels without requiring changes to the data layer, auth, or routing. Best fit is a product with a Brazilian user base where CPF/CNPJ and CEP entry appear in multiple forms — the value is consistency of masking and validation, not capability we could not otherwise build.

Migration path: Treat 5.0.1 as a minor upgrade from 5.0.0. Steps:

1. Confirm our Laravel and Filament versions fall inside the new constraint range (read composer.json at the tag, not the release notes).
2. Run composer update leandrocfe/filament-ptbr-form-fields --with-dependencies in a branch and diff the lockfile — specifically watch for movement in illuminate/* and filament/* transitive versions, which is the real risk of the contracts removal.
3. Execute the full test suite plus a manual smoke pass on every form using the plugin's fields.
4. Verify validation parity: submit invalid CPF/CNPJ and malformed CEP, confirm server-side rules still reject.

No data migrations, no config publishing, no cache clears are required.

Compatibility: The 5.0.x line is appropriate if we are on the Laravel version the maintainer's CI covers. If we are on an older Laravel, stay on the prior pin rather than accepting the widened range — a wider constraint is not an invitation to upgrade the framework.

Sequencing: Land this as an isolated dependency PR, not bundled with feature work or a framework upgrade. If a Laravel major upgrade is also planned, do them in separate changes so a failure can be attributed. Upgrade order: framework first, confirm green, then this plugin.

Operational Impact

Maintenance: Near-zero ongoing cost. Patch releases are Dependabot-driven and arrive frequently; without grouping (e.g. Renovate/Dependabot groups for CI-only actions), expect routine PR noise. Consider auto-merging the dependabot/fetch-metadata and ramsey/composer-install bumps — they are GitHub Actions tooling and cannot affect production runtime.

Support: Community-maintained, single primary author, no commercial backing and no SLA. Acceptable for UI sugar; unacceptable as a load-bearing dependency for anything compliance-adjacent. Note that CPF/CNPJ validation correctness can have business meaning (invoice issuance, KYC) — if that matters, keep a server-side rule of our own rather than relying solely on the client-side field.

Scaling: No scaling implications. No runtime services, no I/O, no background work. Purely request-time rendering and client-side masking.

Failure modes and mitigation:

• Abandonment: Fields silently stop receiving Filament compatibility updates and break on the next Filament major. Mitigation: keep the field list small and documented so replacement is a bounded task; pin the version and upgrade deliberately.
• Client-side-only validation: Masking and validation enforced in the browser can be bypassed. Mitigation: mirror CPF/CNPJ/CEP rules in FormRequest or model-level validation.
• Dependency resolution drift: The contracts removal could let a future composer update pull an untested Illuminate version. Mitigation: commit the lockfile and review Illuminate movements in every dependency PR.
• Unverified framework claim: If the Laravel 13 support is constraint-only, an early framework upgrade could surface breakage with no warning. Mitigation: verify the CI matrix before adopting that pairing.

Ramp-up: Minimal. A developer familiar with Filament reads the plugin's field list in under an hour; the components are declarative and follow Filament conventions. No specialized PT-BR domain knowledge is needed to use the fields, though someone should own the decision on which validation rules are authoritative.

Recommendation: Adopt/retain 5.0.1. It is a low-risk patch on a low-coupling UI dependency, and the widened Laravel compatibility is a net positive for future upgrades. Gate the upgrade on a lockfile diff confirming no unexpected Illuminate movement, and independently verify the Laravel 13 CI claim before pairing it with a framework major upgrade.