Amukana Plvalidator Bundle Laravel Package

Technical Evaluation

What it actually is. Despite being framed as a "Laravel/PHP package," nysander/amukana-plvalidator-bundle is a Symfony bundle (name, structure, and DependencyInjection conventions all indicate this). It ships validation constraints for Polish identifiers: PESEL (national ID, encodes date of birth and gender), NIP (tax ID), REGON (business registry number, 9- and 14-digit variants), Polish identity card numbers, and IBAN/NRB bank account numbers. There is no Laravel service provider, no Rule object, and no laravel/framework constraint.

Architecture fit — poor as a dependency, fine as a reference implementation. A Symfony bundle sits in the wrong abstraction layer for a Laravel or framework-agnostic codebase. Adopting it means either (a) pulling symfony/validator and its transitive graph into a Laravel app that already has its own validator, duplicating infrastructure and error-handling semantics, or (b) forking the constraint classes and rewriting the glue. The actual computational payload — modular checksum arithmetic over digit strings — is a few hundred lines with no framework coupling. The architectural value of the package is near zero; the domain knowledge embedded in it is the only asset.

Integration feasibility — low friction technically, low value strategically. All five validators are deterministic, publicly specified algorithms (PESEL weighted checksum, NIP weights 6,5,7,2,3,4,5,6,7, REGON 9/14 check digits, IBAN mod-97). A mid-level PHP developer can reimplement and test all five in 3–5 days including official test vectors. That sets the ceiling on what this package can save you.

Technical risk — high, concentrated in abandonment.

• Archived: no security response, no PHP-version bumps, no CVE handling, no compatibility fixes.
• 7 stars, 0 dependents: no community validation, no signal that anyone has exercised edge cases in production. The low score (0.1125) is consistent with that.
• 0 declared dependents is a warning, not a comfort: a Symfony bundle with zero composer requires is likely declaring neither symfony/validator nor a PHP floor, meaning undeclared transitive assumptions. Expect PHP 5.6/7.x-era syntax that may fail on PHP 8.2+ (dynamic properties, missing return types, deprecated each/curly-brace offsets).
• Supply-chain: abandoned namespaces are attractive for takeover; with 7 stars the blast radius is small, but internal policy on abandoned dependencies should still apply.

Key questions before any further investment.

1. What does the composer.json actually require — PHP version, Symfony version, declared deps? Does it install and execute at all on PHP 8.2/8.3?
2. Do the validators cover the 14-digit REGON and the newer 12-digit NIP-to-REGON linkage, or only the 9-digit legacy form? Coverage gaps here are silent correctness failures.
3. Is validation syntactic only (checksum plausibility) or does it verify existence? It is almost certainly the former — this distinction must be explicit with stakeholders.
4. Are there test fixtures, and do they include negative cases (off-by-one checksums, PESEL pre-1900 vs. 2000+ month offsets, IBAN with spaces/lowercase)?
5. Who owns the decision to collect PESEL at all? PESEL encodes DOB and gender, so it is personal data under GDPR — necessity and minimisation apply. NIP/REGON are business-entity data and materially lower risk.

Recommendation: do not adopt as a runtime dependency. Use it as a readability reference, extract the checksum logic into an in-house, framework-agnostic pl-identifiers utility, and own it. If a maintained alternative exists (a symfony/validator constraint set on an active release, or a standalone PHP identifier-validation library), prefer it.

Integration Approach

Stack fit. None for Symfony-in-Laravel. The correct shape for a Laravel codebase is a set of custom validation rules (php artisan make:rule PeselRule) backed by pure-PHP value objects, registered via Validator::extend or attribute-style Rule classes. That preserves Laravel's error message, translation, and $request->validate() idioms, and keeps validation failures consistent with the rest of the form layer.

Migration path (from "consider this package" to "we own it").

Total: under two weeks, versus an indefinite maintenance liability for a 7-star archived bundle.

Compatibility. Target a PHP floor and a Laravel major explicitly (laravel/framework: ^10|^11, php: ^8.2) and pin them. Do not carry the bundle's constraint declarations forward — they will be stale or absent.

Sequencing. Do not place this on a critical path. Slot it inside the "Polish market onboarding / PL locale compliance" epic, after the form and data-model decisions are settled, because the validation shape depends on whether you store PESEL as a hash, a masked string, or not at all. If the product only needs to display a Polish tax ID on an invoice, checksum validation may not be a requirement at all — confirm the requirement before building.

One product-level note the package cannot help with. Checksum validation answers "does this look like a valid PESEL/NIP/REGON," not "does this person or company exist." If the business case is KYC or B2B onboarding, the real integration is a registry lookup (GUS REGON API, the Ministry of Finance VAT whitelist), and local validation is a cheap pre-filter that reduces lookup cost and error noise. Frame it that way to stakeholders; otherwise "we validate NIP" will be heard as "we verify counterparties."

Operational Impact

Maintenance. Adopting the bundle means inheriting an unmaintained component with no upgrade path. Every PHP or Laravel major bump becomes an internal fork-and-patch exercise — cheap per instance, but recurring and poorly tracked. Owning ~400 lines of checksum code with a frozen, fully-specified algorithm set is close to zero-maintenance by comparison; these algorithms do not change.

Support. No maintainer, no issue triage, no upstream answers. Any defect becomes an internal debugging task against opaque third-party code. Conversely, an in-house implementation means the person who understands PESEL month-offset encoding is on your team — a real operational advantage when a customer disputes a rejected identifier.

Scaling. Effectively zero concern. String inspection and modular arithmetic are CPU-trivial; even form-heavy traffic is negligible next to I/O. If PESEL is ever used inside a high-volume ingestion path, batch validation should be run once at ingestion, not per row read. No caching layer, queue, or external call is involved.

Failure modes to design for.

• False rejection of valid identifiers — the worst outcome: it blocks legitimate Polish customers at signup. Highest risk areas are 14-digit REGON, PESEL birth-century encoding, and input formatting (spaces, hyphens, mixed case, full-width digits).
• False acceptance — a checksum-valid but nonexistent identifier passes; only registry lookup catches this.
• Silent drift — if the archived code is vendored with edits and no tests, a later refactor can regress a checksum weight with no test to catch it.
• Locale/collation surprises — identity card numbers mix letters and digits; ensure case folding is deterministic and not locale-dependent.
• PII exposure in logs — Laravel's validation failure messages and Log::debug payloads can leak PESEL. Mask it in exception handlers and validation output; make this an explicit acceptance criterion, not a code-review nicety.

Ramp-up. Small. A backend developer unfamiliar with Polish identifiers can reach competence in a day: the specifications are public, the checksums are simple, and the official registries publish test data. The domain ramp-up is not the risk — the risk is that a 30-minute "just install the bundle" decision quietly commits the team to owning an abandoned dependency for the life of the product. Cost the in-house build in the epic; it is the cheaper and lower-variance option.