Filament Cnpj Field Laravel Package

Technical Evaluation

Architecture fit. The package is a Filament form-field plugin, not a general-purpose CNPJ library. It contributes a single field type (CnpjInput) to Filament's form builder and delegates validation/lookup to jeffersongoncalves/laravel-cnpj. That is a deliberately narrow architectural footprint: one class registered in a form schema, no service provider hijacking of core behavior, no persistence layer of its own. For any application already running Filament panels, this is a low-coupling addition. For anything outside Filament, it is not applicable — the underlying laravel-cnpj package would be the correct integration point instead.

Integration feasibility. Presumed to be a standard Composer install plus a field reference in the form schema (CnpjInput::make('cnpj')). Effort is measured in hours, not days, provided the host application is already on Filament v5. The three capabilities — mask, check-digit validation, and Minha Receita lookup — are independently valuable and should be independently toggleable; that configurability is the main thing to confirm before committing.

Technical risk. Several concerns warrant flagging to the steering group:

• Filament v5 maturity. This is an "initial release for Filament v5," which means the package is tracking a very new major of Filament. Ecosystem packages, documentation, and community answers lag major releases by months. Expect rough edges in the host framework, not just this package.
• Version number vs. history. A first release numbered 3.0.0 implies either a squashed/renamed history or a versioning scheme aligned to Filament's major. Neither is disqualifying, but it means we cannot infer stability from the version number the way we normally would. Treat this as a v0 package.
• Single-maintainer, two-package dependency chain. Both the field package and laravel-cnpj appear to sit with the same author. Concentration risk is real: one person's availability governs our ability to patch a validation bug.
• External API dependency. The Minha Receita lookup is a third-party HTTP call. Latency, rate limits, uptime, and terms of use are outside our control and outside this package's control.
• Specification volatility. Brazil's alphanumeric CNPJ format is a forward-looking change tied to Receita Federal's rollout. Mask and check-digit rules for the alphanumeric variant are non-trivial and could still shift. A validation bug here produces silent data-quality defects, which are far more expensive than a broken form.
• Blocking I/O in a form request. Lookup-on-blur or lookup-on-submit executes a synchronous outbound call inside a user-facing request. That is a latency and availability coupling we need to understand precisely.

Key questions for the maintainer / spike.

1. Does the field validate both numeric and alphanumeric CNPJ, or only one, and where is that switch configured?
2. Is the lookup synchronous, and can it be disabled or deferred (queued) without losing validation?
3. What happens when Minha Receita is unreachable — fail open (accept syntactically valid input) or fail closed (block submission)?
4. Are there config hooks for endpoint override, timeout, retry, and response caching?
5. What are the exact Composer constraints (PHP, Laravel, Filament, laravel-cnpj)?
6. Is there test coverage for the check-digit algorithm, including the alphanumeric case? Can we see it?
7. Is there any intent to support Filament v4, or is v5-only a hard line?
8. License and support expectations — is this a community package or is there a commercial backer?

Integration Approach

Stack fit. Requires Laravel (presumed 11/12) plus Filament v5. If our target application is on Filament v3 or v4 — still the common case — this package is not usable today and the decision is really "when do we move to Filament v5," which is a much larger question than a CNPJ field.

Migration path. Effectively greenfield; there is no prior assessment and no incumbent to displace. The real migration concern is data, not code: if we already store CNPJ values, we must confirm the storage column is a string type wide enough for alphanumeric CNPJ (14 characters, now potentially non-numeric). Any BIGINT/NUMERIC CNPJ column becomes a hard blocker and a schema migration. Masked values must be normalized (strip punctuation and, if applicable, casing) before persistence.

Compatibility. Verify no collision with an existing CNPJ validation rule or another Filament CNPJ field — duplicate field names or competing service providers are the most likely integration failure. Also confirm the package's Filament constraint is a minor-tolerant range, not a pinned 5.0.x, or every Filament patch release becomes our problem.

Sequencing.

1. Spike (1–2 days). Install in a sandbox panel, exercise numeric and alphanumeric CNPJs, deliberately take the lookup endpoint offline, inspect the config surface, review the test suite.
2. Pilot (1 sprint). One non-critical form. Instrument lookup latency and failure rate. Add an application-side cache in front of lookups regardless of whether the package offers one.
3. Harden. Wrap or subclass the field to enforce our timeout, caching, and fail-open policy rather than relying on package defaults.
4. Roll out to remaining forms only after the pilot shows acceptable lookup reliability.
5. Defer entirely if the host app is not on Filament v5 and no upgrade is already planned.

Operational Impact

Maintenance. Two packages to track, both young and both single-maintainer. Pin exact versions, subscribe to release notifications, and budget a small recurring allowance for tracking Filament v5 minor releases — field packages break on form-API changes more often than on anything else. Our fork-or-wrap posture should be decided up front: if we subclass the field to add caching and timeout policy, upgrades become cheaper and we insulate ourselves from abandonment.

Support. No SLA, no vendor to escalate to. Internal owners must be able to read the validation and lookup code — small enough to audit in an afternoon, which is the main mitigating factor. Support desk needs a script for "the company lookup isn't returning anything," because that will be the dominant ticket.

Scaling. The lookup is the scaling hazard, not the field. Every form interaction potentially triggers an outbound HTTP call; under load that becomes both a latency tax on our request workers and a load tax on a public, unpaid third-party service. Mitigations: debounce, cache aggressively by normalized CNPJ (company data changes rarely), and consider moving lookup off the submit path. Also watch database write volume if lookup results are persisted.

Failure modes.

• Minha Receita unavailable or slow → form submission stalls or blocks. Highest-probability incident; must be fail-open by policy with a manual-entry fallback.
• Rate limiting → intermittent lookup failures that look like data errors to users.
• Alphanumeric validation defect → valid CNPJs rejected or invalid ones accepted; silent, and expensive to remediate after data entry.
• Alphanumeric value written to a numeric column → truncation or rejection at the database layer.
• Filament v5 upgrade → field breaks at render time, taking the whole form with it.
• Maintainer abandonment → no security patches; mitigated only by our ability to fork a small codebase.

Ramp-up. Low for engineers already fluent in Filament: roughly half a day to first working field, one to two days to a production-hardened integration with our own caching and failure policy. The larger organizational lift is not engineering — it is briefing support, data, and compliance stakeholders on the numeric-to-alphanumeric CNPJ transition so that downstream systems and validators are ready on the same timeline. That communication work should start alongside the pilot, not after rollout.