Idcard Laravel Package

Technical Evaluation

Architecture fit. ionepub/idcard is a narrowly scoped utility: an 18-digit PRC resident ID validator that also derives birth date, gender, age, and administrative region from the number. It is not a Laravel package in any meaningful sense — there is no service provider, config, facade, or validation rule shipped. It is a plain PHP class that a Laravel application would wrap. That is actually a point in its favor for architecture fit: the surface area is small enough to isolate behind an internal adapter (e.g. App\Support\Identity\IdCardValidator) so the vendor class never leaks into controllers, FormRequests, or models. The algorithmic core — the ISO 7064:1983 MOD 11-2 check digit, the YYYYMMDD birth segment, the odd/even gender parity, and the GB/T 2260 six-digit region prefix — has been stable since the 1999 specification, so the logic itself is not a moving target. What does move is the region lookup table, and that is where the package's age (last release August 2020) becomes a genuine concern.

Integration feasibility. Straightforward. Composer install, PSR-4 autoload, instantiate and call. The realistic integration points in a Laravel codebase are: a custom ValidationRule for FormRequests handling KYC/onboarding/profile forms, a value object or cast for the stored identifier, and a service-layer call for the derived attributes (age bands, region) used in reporting. There is no queue, no external HTTP call, and no database dependency, so integration is a half-day of work plus test coverage. The caveats are mundane but real: the package was published before PHP 8 was mainstream, so composer.json platform constraints, deprecated dynamic properties, and implicit-nullable parameter signatures need verification on your target PHP version (8.2/8.3). The check digit's X can arrive as lowercase from user input and must be normalized before validation.

Technical risk. Three risks dominate, ranked:

1. Region data staleness (high likelihood, medium impact). Chinese administrative divisions are reorganized regularly — county-level cities are upgraded, districts are merged, new development zones are carved out. A 2020-vintage table will misreport region names for numbers issued under newer codes, and may reject codes that did not exist at the time. Whether this is a hard failure or a cosmetic one depends on whether your product gates on region validity or merely displays region name.
2. Abandonment (high likelihood, medium impact). 26 stars, zero dependents, a single maintainer, and no release in roughly five years. There is no community to absorb a bug report. Packagist will keep serving the artifact, but the upstream repository could go quiet or disappear.
3. PII handling (medium likelihood, high impact). The package encourages passing raw ID numbers around. Under PIPL, ID numbers are sensitive personal information: collection requires a lawful basis and separate consent, storage should be minimized and encrypted, and logs must never capture the raw value. A validator that returns a rich object invites developers to persist or log that object wholesale.

Key questions for the evaluation spike.

• Does the package reject impossible dates (e.g. 20230230, Feb 30) and future birth dates, or only check the checksum and date format?
• How does it handle 15-digit legacy IDs, whitespace, and lowercase x?
• What is the region table's source, granularity (province/city/county), and shipping date — and does a miss fail closed or open?
• What PHP versions does composer.json declare, and does it install cleanly on our target runtime under --prefer-lowest?
• How is "age" computed — server timezone, Asia/Shanghai, or caller-supplied reference date? Birthday-boundary correctness matters for age-gated features.
• Is the license header intact in source (MIT permits vendoring, which is likely our endgame)?

Integration Approach

Stack fit. Good, with a wrapper. The package slots in as a leaf dependency with no framework coupling, no service container assumptions, and no global state. For a Laravel app it should be treated as an implementation detail of one internal service class, with a small value object (IdCard) exposing isValid(), birthDate(), gender(), ageOn(CarbonImmutable $date), and region(). Pass a reference date explicitly rather than relying on now() so age calculations are testable and timezone-explicit. Do not bind the vendor class directly in the container — bind the interface you own.

Migration path. Treat this as a reference implementation, not a long-term dependency. The pragmatic sequence: (1) run a spike that exercises the package against a hand-built vector set of ~40 numbers covering all check digits including X, leap days, invalid dates, boundary region codes, and 15-digit inputs; (2) if the algorithm holds, vendor the MIT-licensed source into app/Support/Identity/ (or a first-party packages/ module) with attribution preserved, and own the region dataset ourselves; (3) only if the team prefers not to own code, keep the Composer dependency but pin it exactly and mirror it. Given the maintenance profile, vendoring is the lower-risk path — the algorithm is a few dozen lines and the region table is the only thing that needs a refresh cadence regardless of who "owns" the package.

Compatibility. Verify against the actual runtime: PHP 8.2/8.3 deprecations, strict types, and any use of strlen/substr on multibyte region names (region names are UTF-8 Chinese; the six-digit code handling is byte-safe but any string manipulation on names is not). Confirm the package does not depend on the deprecated mbstring.func_overload. If we vendor, this is moot — we rewrite to our own standards and add declare(strict_types=1).

Sequencing.

1. Spike (1–2 days): vector testing, PHP version check, region table inspection. Go/no-go on vendoring vs. dependency.
2. Adapter + value object: internal interface, normalization of input (trim, uppercase X), explicit reference date for age.
3. Laravel validation rule: new IdCardRule() usable in FormRequests; fail with a translatable message; never echo the input back in the error payload.
4. Region data refresh: decide the failure semantics on unknown code (recommend: accept the number as structurally valid, return region as null, log a metric — do not reject a user because our table is stale).
5. PII treatment: storage encryption or hash-plus-derived-fields, log scrubbing, retention policy. This should land with the validation rule, not after.
6. Observability: counters for invalid checksum, unknown region code, and normalization events.

Operational Impact

Maintenance. Low code maintenance, non-trivial data maintenance. The checksum will not change; the region table will. Budget an annual refresh tied to the Ministry of Civil Affairs' published division changes, plus an ad-hoc path when a support ticket surfaces an unknown code. If we carry the Composer dependency, we inherit a maintainer who has not shipped since 2020 — assume no upstream fixes and plan to fork on first defect.

Support. The failure modes users will actually report are "your form rejects my real ID" (stale table, or a normalization bug on x/whitespace) and "it says I'm from the wrong city" (outdated region mapping). Both are diagnosable in minutes if the adapter logs the failure category rather than the raw number. Tier-1 support must not be able to read ID numbers in logs — document this explicitly.

Scaling. Effectively free. Validation is pure CPU on an 18-character string; the only cost is loading the region array. If the table is a large in-file PHP array, ensure it is opcache-friendly and, ideally, lazy-loaded only when region() is called — the common path (checksum validity) should not pay for it. No I/O, no network, no contention. This will never be a bottleneck at any realistic request volume.

Failure modes.

• Silent over-acceptance: checksum-only validation passing impossible dates → garbage downstream in age/gender analytics. Mitigate with explicit date plausibility checks in the adapter.
• Silent over-rejection: stale region table causing valid users to fail onboarding. Mitigate by never gating on region lookup.
• Timezone drift: age computed in UTC for a user in UTC+8 flips one day early around midnight, affecting age-gated eligibility. Mitigate with an explicit Asia/Shanghai reference date.
• PII leakage: raw ID in exception messages, Laravel's ValidationException payloads, Telescope/Horizon logs, or Sentry breadcrumbs. Mitigate with redaction at the adapter boundary and a policy that the value object never implements __toString() returning the raw number.
• Dependency disappearance: upstream repo archived or removed. Mitigate by mirroring or vendoring.

Ramp-up. Engineer ramp-up is hours — one class, one algorithm, well-documented in the national standard. The real ramp is domain and compliance knowledge: the GB/T 2260 region code semantics, PIPL obligations for sensitive personal information, and the business rules around what "valid" means for your product (structurally valid ≠ issued ≠ belongs to the claimant). A TPM should treat the compliance review as the critical path, not the code. Assign one engineer as owner of the region dataset and the annual refresh, and make the validation rule's error copy reviewed by legal before launch.