Identity Number Bundle Laravel Package

Technical Evaluation

Architecture fit — Nominally poor at the framework boundary, sound at the domain boundary. This is a Symfony bundle: its value is a DI extension, form types, and symfony/validator constraint classes. A Laravel application has no service provider, facade, or Illuminate\Validation\Rule integration here, so the bundle itself is dead weight in our stack and pulls a framework we do not run. The reusable asset is the underlying jongotlin/identity-number library, which is plain PHP and therefore stack-agnostic. Treat the bundle as a worked example of intended usage, not as an installable dependency.

Integration feasibility — High on the library path, low on the bundle path. composer require jongotlin/identity-number, then author a ValidationRule, an error message, and a singleton binding is a day's work for a mid-level engineer. The bundle path requires either running Symfony components inside Laravel or forking the constraint, both of which cost more than rewriting the ~100 lines of checksum logic. The decision is not close.

Technical risk — The dominant risks are provenance and documentation, not algorithms.

• Abandonment: zero stars, zero dependents, single maintainer, score 0. Assume the dependency is already unmaintained and plan accordingly.
• Documentation inconsistency: the package description claims South African ID numbers (length, checksum, date of birth, gender, citizenship), while the substantive assessments describe Swedish personnummer, samordningsnummer, and organisationsnummer. Either the description is a template error or there are two divergent surfaces. This must be resolved before we write a line of integration code — it determines which market's onboarding funnel we are unblocking.
• Domain edge cases: Swedish numbers require 10- vs 12-digit normalization, +/- separator semantics for individuals over 100, coordination-day offset (+60), organisation-number prefix ranges, and reserved test ranges. Missing any of these produces false rejections of legitimate users, the highest-severity failure at signup.
• Semantic overreach: Luhn and format rules prove structure, not existence. This is validation, not verification. Any product requirement that reads "confirm the customer is real" is out of scope and needs a separate BankID/Skatteverket/Navet decision.
• Dependency drift: Composer constraints on PHP and Symfony components will eventually conflict with a current Laravel release.

Key questions

• Which market and number type is actually in scope — South Africa or Sweden? The documentation contradicts itself.
• What does the underlying library pin for PHP and symfony/*, and does that resolve against our target Laravel version?
• Does the API accept 10- and 12-digit forms and both separators, and is coordination-number acceptance opt-in?
• Does it return false on malformed input, or throw?
• Are test-number fixtures or generators included? That determines how much of our acceptance suite we must author.
• Is there a maintained fork, and what is the release cadence over the last 12 months?

Integration Approach

Stack fit — Clean. Pure PHP string and arithmetic logic, no I/O, no persistence, no async, no native extensions. It fits Laravel 9/10/11 on the library path. The only Laravel-native artifacts we author are a ValidationRule, a message key, and optionally a cast or value object so a validated number cannot re-enter the domain as a raw string.

Migration path — Three realistic entry states:

1. Free-text or regex today: swap the regex for the library call behind the same rule name and message key. Lowest risk, largest payoff — this is the recommended starting case.
2. Existing third-party validator: run both behind a flag for one release, log disagreements, then cut over. Preserves user-facing messages and gives us a measured confidence interval before we commit.
3. Symfony in the same estate: extract to the library plus a thin adapter anyway; do not carry the bundle across as shared infrastructure.

Compatibility — Verify php and any transitive symfony/validator constraint against the target Laravel version before anything else. If the bundle forces a Symfony major that conflicts with Laravel's own transitive Symfony components, the bundle path is disqualified outright and the library path is confirmed. MIT licensing means vendoring or forking with attribution is a legitimate and probably preferred fallback.

Sequencing

1. Resolve the South Africa vs. Sweden documentation conflict; confirm the underlying library's API surface by reading its source.
2. Spike the ValidationRule plus a fixture corpus: valid and invalid numbers for each type, plus coordination numbers and malformed/whitespace inputs.
3. Record an ADR choosing library over bundle, with the abandoned-dependency rationale written down.
4. Integrate into registration/onboarding, then admin and CSV import paths.
5. Ship behind a feature flag with structured logging of rejections for the first weeks.
6. Assign internal ownership of the forked/vendored copy before the dependency becomes load-bearing.

Operational Impact

Maintenance — Budget for ownership transfer, not dependency management. Pin the version, calendar a periodic upstream review, and keep a documented fork contingency. The code is small enough to read in one sitting, which is exactly what makes vendoring cheap and makes leaving it unexamined indefensible.

Support — There is no vendor, no community, and no SLA. That means internal documentation of the rule's semantics, its error messages, and — critically — the line between format validation and identity verification is mandatory, not optional. Compliance and support teams will test that line, and a support agent who believes a passing check means "verified person" is a regulatory incident waiting to happen. Provide a manual-override path in support tooling for legitimate users who fail the check.

Scaling — Effectively free. Microseconds of CPU per call, no network or database round trips, trivially cacheable, no capacity planning required. This is true even at signup-spike volumes.

Failure modes

• False rejection of a legitimate identity or company number — user-facing, high severity, and the fastest route to a social-media complaint. Mitigate with a curated fixture corpus, permissive parsing of separators and digits, and a support override.
• Silent acceptance of well-formed but non-existent numbers — mitigate by scoping every product claim to format validation and layering a real verification provider where the business requires proof.
• Exceptions on malformed input — wrap the call defensively inside the rule so garbage input yields a validation message, not a 500.
• Behaviour drift on a minor upgrade — pin, and keep the fixture suite as a regression gate.
• Upstream abandonment plus PHP version drift — fork or vendor; this is a when, not an if.

Ramp-up — Hours for a mid-level Laravel engineer to wire the rule and binding; the real learning curve is Swedish (or South African) identity-number domain knowledge, not PHP. Source test numbers from the issuing authority's published test ranges rather than inventing them, and encode them as CI fixtures so the knowledge lives in the repository rather than in one engineer's head.