Cpf Cnpj Laravel Package

Technical Evaluation

What the package is. stonkeep/cpf-cnpj is a single-purpose Laravel Nova field that renders an input for Brazilian CPF (individual) and CNPJ (company) tax identifiers, presumably applying input masking and check-digit validation on top of Nova's base Field class. Its entire functional surface is likely one or two PHP classes plus a Vue component.

Architecture fit. Adoption is gated on a hard prerequisite: the application must already run Laravel Nova, a paid, closed-source admin panel with per-project licensing. If the product's back office is built on Filament, Livewire, Inertia, or a bespoke Blade admin, this package is architecturally irrelevant — there is no partial-fit path. Even within Nova, the value is narrow: it improves one form input. It contributes nothing to API validation, imports, queue jobs, or domain modeling, so CPF/CNPJ rules would still need to be enforced server-side elsewhere (FormRequests, model casts, DB constraints).

Integration feasibility. Mechanically trivial — composer require, register the field in a Nova resource, done. The real feasibility question is version compatibility: Nova 4 and Nova 5 have meaningfully different field APIs and asset pipelines, and a package at zero stars/zero dependents has almost certainly been tested against exactly one Nova major version. There is no CI badge, changelog, or release cadence to inspect.

Technical risk — high, concentrated in three areas:

1. Bus factor of one. A single maintainer, no dependents, no stars, no visible downstream usage means no community pressure to fix breakage. A Nova upgrade or a PHP minor release can orphan the package silently.
2. Correctness of validation logic. CPF/CNPJ check-digit algorithms are well-specified but easy to implement subtly wrong (leading zeros, rejecting repeated-digit sequences, reformatting on paste). A field that only masks on the front end and does not validate server-side provides cosmetic compliance, not data integrity — bad CPF/CNPJ data propagates into billing, invoicing, and fiscal integrations.
3. Format drift. Brazil's Receita Federal is moving CNPJ to an alphanumeric format (announced for 2026). A dormant micro-package is a poor bet to absorb that change; an in-house field is a one-line regex update.

Key questions for the maintainer / spike:

• Which Nova major versions are supported, and is Nova 5 tested?
• Does validation run server-side (a Nova rules() call) or only as a JS mask?
• How is the value persisted — raw digits or formatted string? (Raw digits are strongly preferred; formatted storage breaks joins and indexing.)
• Does it accept both CPF and CNPJ in one field with automatic type detection, or is it one field per type?
• Is there any test suite, and what is the license?
• Does it tolerate the upcoming alphanumeric CNPJ?

Verdict. Do not adopt as a dependency of record. Either fork it and own the ~150 lines, or implement the field in-house and pair it with a maintained validation library for server-side rules.

Integration Approach

Stack fit. Requirements are Laravel + Nova + a supported PHP version. The package addresses presentation and input hygiene only; it must be paired with a server-side validator. The reliable choice is a mature PT-BR validation package (e.g. laravellegends/pt-br-validator, which supplies cpf and cnpj rules) rather than relying on the field's client-side behavior. Persist as CHAR(14) (digits only) with a formatter/cast for display.

Migration path. Greenfield: register the field on the relevant Nova resources, add the validation rule to the corresponding FormRequest or Nova rules(), and add a model accessor for formatted output. Brownfield with existing CPF/CNPJ columns: run a one-off audit/normalization job before enabling validation, because legacy rows likely contain a mix of masked and unmasked values — enabling strict validation on a resource with dirty data produces save failures that look like regressions to users.

Compatibility and sequencing.

1. Spike (½ day): install in a scratch Nova app, confirm Nova version support, verify server-side vs client-side validation, inspect persistence format.
2. Decide build-vs-fork: given the fork is small, prefer vendoring into an internal nova-fields package so upgrades are under your control.
3. Implement server-side rules and normalization independently of the field — this is the durable layer.
4. Roll out field-by-field, starting with a low-traffic resource, and pair with the data normalization job.
5. Pin the dependency to an exact version (or a VCS fork ref) and add it to the upgrade checklist for every Nova and PHP bump.

Operational Impact

Maintenance. The dominant cost is not the package itself but the unowned upgrade risk: every Nova and PHP upgrade becomes a manual check against a dependency nobody maintains. Forking internalizes this and reduces it to near zero, at the cost of ~1–2 days of engineering plus ongoing ownership of a small file. Leaving it as an external dependency trades that upfront cost for recurring, unbounded risk at upgrade time.

Support. No vendor, no SLA, no security disclosure process. A vulnerability in the field would surface through your own review, not an advisory. For an admin-panel input this is a low-severity exposure (authenticated back-office users only), but it should be recorded in the third-party inventory with a "no upstream support" flag.

Scaling. Negligible performance impact — it is a form input. No query, cache, or throughput considerations. The scaling concern is organizational: one more micro-dependency multiplies the surface a platform team must audit across many Laravel services.

Failure modes.

• Nova major upgrade breaks the field's asset compilation → admin panel forms fail to render or the field silently degrades to a plain text input (worst case: validation appears present but isn't).
• Mask accepts a value that the server-side rule rejects → confusing user-facing save errors.
• Formatted values persisted → downstream fiscal integrations (NF-e, ERPs) reject or mis-parse the identifier.
• Alphanumeric CNPJ rollout → field rejects valid new-format identifiers, blocking company registration for affected customers.

Ramp-up. Essentially zero for a Laravel developer — it's a Nova field registered like any other. The genuine ramp-up is domain knowledge: CPF/CNPJ check-digit semantics, the raw-vs-formatted storage convention, and the 2026 alphanumeric change. Budget that as product/ops context, not engineering time.

Recommendation. Treat as a reference implementation, not a dependency. Allocate ~2 days to fork or rebuild the field, own the validation server-side with a maintained rules package, and standardize on digits-only storage with display formatting. The package is a reasonable starting point precisely because it is small enough to absorb.