Nip Validator Bundle Laravel Package

Technical Evaluation

Architecture fit — the package is not what the brief assumes. kreyu/nip-validator-bundle is a Symfony bundle, not a Laravel package. It targets Symfony >=6.1, ships a Bundle subclass and a DI extension, and depends on symfony/validator Constraint classes (Nip, Tin). Laravel does not boot a Symfony Kernel and does not expose Symfony's constraint registry — Laravel's validator is Illuminate\Validation with its own Rule contract. The bundle therefore cannot be installed and used as-is in a Laravel application; only its underlying checksum logic is portable. This is the single most important finding for scoping.

Technical risk. Low code complexity, high supply-chain risk:

The domain logic itself (Polish NIP: 10 digits, weighted checksum mod 11, reject when remainder is 10) is stable and well-specified, so staleness is a packaging risk rather than a correctness risk. The Tin constraint's semantics are less obvious from the bundle surface and need confirmation — it may be a generic alias or a genuinely different format, and misinterpreting it is a real correctness hazard.

Key questions for the maintainer/team:

1. Is the target application Laravel or Symfony? If Laravel, this is a reference implementation, not a dependency.
2. What exactly does Tin validate versus Nip — country scope, length, checksum?
3. Does the constraint normalize input (dashes, spaces, PL prefix) before checksumming, or reject non-canonical strings?
4. Is there a Symfony 7 / PHP 8.3 compatibility path, and who owns it?
5. Are there known false-negative reports on the checksum edge case (remainder == 10)?

Integration Approach

Stack fit. For a Laravel target (10.x/11.x, PHP 8.1+), the bundle's framework plumbing is dead weight; the validator rules are ~50 lines of arithmetic. Two viable paths:

• Vendor the logic (recommended): lift the checksum implementation into a first-party Illuminate\Contracts\Validation\ValidationRule implementation (NipRule, TinRule), register user-facing messages in a lang file, and add Pest/PHPUnit coverage against a corpus of valid/invalid NIPs. Cost: ~1 engineer-day. Removes the abandoned dependency entirely.
• Bridge Symfony's validator: install symfony/validator and invoke Constraint validators manually inside a Laravel rule. Technically feasible but adds a second validation paradigm, a heavy transitive dependency, and translation-domain friction for zero benefit. Reject unless the org already standardizes on Symfony constraints.

If the target is genuinely Symfony 6.1/6.2, direct composer require kreyu/nip-validator-bundle works and is the correct low-effort choice — but pin the version and treat it as a vendored fork candidate.

Compatibility. PHP 8.1+ aligns with Laravel 10/11 minimums; the symfony/validator version constraint is the friction point if bridged. No conflict with Laravel's bundled Symfony components (console, http-foundation, process, etc.) since validator is not among them.

Sequencing.

1. Spike (0.5d): confirm Laravel vs Symfony target; read the constraint source; extract the checksum.
2. Spec (0.5d): document input normalization rules, Nip vs Tin semantics, and error message copy with the business owner.
3. Implement (1d): first-party rule class + tests (property-based tests against generated NIPs are cheap and catch the mod-11 edge case).
4. Wire (0.5d): attach to the relevant form requests / API resources; add a Rule::when guard if the field is optional.
5. Retire: do not add the bundle to composer.json.

Operational Impact

Maintenance. Near-zero ongoing cost once vendored — the checksum algorithm is a Polish statutory constant and does not drift. Retaining the dependency, by contrast, means inheriting an unmaintained package with one maintainer and no dependents; every future PHP/Symfony major becomes an unowned upgrade task. Vendoring is the operationally cheaper option despite the small upfront cost.

Support. No commercial support, no SLA, MIT with no warranty. Acceptable for a self-contained checksum; unacceptable as a critical-path dependency. Escalation path is "read the source," which is feasible here because the source is tiny.

Scaling. Non-issue. Validation is stateless, O(1) per field, no I/O, no allocation pressure. It will not appear in any performance profile.

Failure modes to instrument:

• False negatives on valid NIPs — the mod-11 remainder-10 case and any leading-zero handling. Silent rejection of a legitimate business partner is the costly failure; log rejected values (hashed or masked) at debug level during rollout.
• Format brittleness — users paste 123-456-32-18 or PL1234563218; if the validator rejects rather than normalizes, support tickets follow. Decide normalization vs. strictness explicitly and document it in the API contract.
• Tin semantic drift — if the constraint is broader than NIP, using it as a drop-in may accept identifiers the downstream tax system rejects.
• Dependency drift (if the bundle is installed) — a future Symfony major silently breaks form submission until someone notices.

Ramp-up. Trivial. A mid-level PHP engineer unfamiliar with the codebase can own this end-to-end within a day, provided the Nip vs Tin question is answered by someone with domain knowledge. The real onboarding cost is the Polish tax-ID domain, not the code.