Laravel Cnpj Laravel Package

Technical Evaluation

This release (1.0.2) changes the distribution mechanism of the package's migration from a directly-shipped migration file to a publishable .stub, aligning with the de facto Laravel package convention (Spatie/Orchestra-style). For a TPM, the important read is that this is a packaging-convention change, not a functional change: the publish command and tag (cnpj-migrations) are unchanged, so consumer-facing behavior is preserved.

• Architecture fit: Strong. Shipping migrations as .stub files published via vendor:publish is the idiomatic Laravel pattern. It prevents the package's migration from colliding with the host application's migration namespace and puts schema ownership in the consuming app, which is exactly where Laravel expects it. A package that persists CNPJ records (evidenced by create_cnpj_table) touches business-critical identity data, so keeping schema under the app's control is the right call.
• Integration feasibility: Low friction. Standard composer require → php artisan vendor:publish --tag="cnpj-migrations" → php artisan migrate flow. The unchanged tag means existing docs, CI scripts, and deployment runbooks remain valid. No config or API surface change is implied.
• Technical risk: Low-to-moderate, concentrated in areas the release note does not address. The stub rename means any automation that hard-coded the old published filename (e.g., a CI step copying create_cnpj_table.php from the vendor path, or a test asserting on migration filenames) will silently break. Risk is otherwise bounded: the CNPJ domain itself (14-digit identifier, mod-11 check digits, alphanumeric CNPJ transition in Brazil) is well-specified, but the package's correctness on validation/formatting and its handling of the new alphanumeric CNPJ format are unverified from this note alone.
• Key questions:
  • Does the package expose a Laravel validation rule (cnpj), a formatter/caster, an Eloquent model, or all three? The assessment's integration effort depends heavily on this.
  • Is the cnpj table a persistence store for application-owned CNPJ records, or a reference/lookup table shipped with seed data? This determines data-ownership and LGPD exposure.
  • Does the model/validation support the alphanumeric CNPJ format mandated by Receita Federal (effective mid-2026)? This is the single largest forward-looking technical risk.
  • What Laravel and PHP version matrix is supported (Laravel 9/10/11/12, PHP 8.1+)? Is illuminate/support constrained appropriately?
  • Is there a published changelog and semantic-versioning discipline? A 1.0.2 patch for a stub rename is plausible, but I want evidence of a release process.
  • Maintenance signals: last commit date, open issue count, CI status, maintainer count.

Integration Approach

• Stack fit: The package assumes a conventional Laravel application with standard migration and service-provider bootstrapping. It will fit cleanly into any Laravel codebase that already uses vendor:publish for third-party packages. It is not a fit for Lumen-without-facades setups, non-Laravel PHP applications, or teams that manage schema exclusively through an external migration tool (Flyway, Liquibase, Doctrine) — the stub must be published and version-controlled into the app's database/migrations directory.
• Migration path: For new adopters, the flow is unchanged: install, publish the cnpj-migrations tag, review the published stub, then php artisan migrate. Because it is now a stub, the team should treat the published file as application-owned source, review it in PR, and commit it — not regenerate it on every deploy. For existing 1.0.x consumers, there is no action: their previously published migration remains in place and the rename is inert. Teams should not re-publish over an existing migration; vendor:publish will prompt before overwriting.
• Compatibility: No breaking change to the public PHP API, config keys, or publish tag is implied. The only compatibility contract that moves is the filename of the shipped stub. Any internal CI, scaffolding template, or onboarding script referencing the old vendor path must be updated. PHP/Laravel version compatibility cannot be confirmed from this note and should be verified against composer.json before approval.
• Sequencing:
  1. Confirm framework/PHP support matrix against the host application.
  2. Spike in a non-production branch: install, publish, inspect the generated schema (column types, indexes, uniqueness on the CNPJ value, timestamps, soft deletes).
  3. Decide whether the schema meets application requirements or needs an additive app-side migration (recommended over editing the stub, to keep upgrade paths clean).
  4. Integrate validation/formatting at the domain boundary (form requests, DTOs) before wiring persistence.
  5. Add the published migration to source control and CI migration checks.
  6. Only then roll to staging and production, behind the normal migration gate.

Operational Impact

• Maintenance: The package is at 1.0.x and the release is a housekeeping change, which is a mildly positive signal for hygiene but says nothing about ongoing stewardship. A stub-based migration reduces maintenance for the consumer (no vendor-file conflicts on upgrade) but increases it slightly for the maintainer (stub must be kept in sync with any schema changes). Expect the bus factor to be low on a single-purpose CNPJ package; plan for the possibility of forking or internalizing the validation logic.
• Support: Support burden is mostly upstream GitHub issues plus internal knowledge of the published schema. Because the migration now lives in the app, schema drift is our problem, not the vendor's — a support ticket asking "why doesn't the table have an index on the CNPJ column?" will land on our team, not the package author. Document the published schema in the internal runbook.
• Scaling: Persistence-layer scaling depends entirely on what the table stores. If it is an application-owned CNPJ registry, expect growth proportional to business entities (modest) and ensure the CNPJ column is uniquely indexed and the validation is enforced at the database level, not only in PHP. If it is a reference dataset of all Brazilian CNPJs, that is tens of millions of rows and a fundamentally different operational profile — confirm which before sizing anything.
• Failure modes:
  • Publish overwrite: running vendor:publish on upgrade with --force clobbers the app-owned migration; guard against this in deploy scripts.
  • Silent filename dependency: CI or scaffolding referencing create_cnpj_table.php in the vendor path breaks after this release.
  • Invalid stored data: if validation lives only in the package's rule and is bypassed by seeders, imports, or queue jobs, invalid CNPJs enter the table; enforce with a DB constraint or model-level guard.
  • Alphanumeric CNPJ transition: if the package hard-codes a numeric-only regex, it will reject valid CNPJs once the new format lands; this is a scheduled failure, not an incident, and should be tracked now.
  • LGPD exposure: CNPJ is generally public company data, but linkage to contacts and contracts can make the table personally identifiable in context; classify it in the data inventory.
• Ramp-up: Very low for any developer familiar with Laravel's package conventions — under an hour to install, publish, and migrate. The real learning curve is domain-side, not framework-side: onboarding should cover CNPJ semantics, check-digit validation, formatting expectations in the UI, and the alphanumeric format timeline. Budget roughly half a day per engineer for domain context, and add the published migration and publish command to the standard package onboarding checklist.