Axiom Laravel Package

Technical Evaluation

Package category: The release note ("Added Vietnamese citizen rule") confirms this is a Laravel validation-rule package with locale-specific identity validators. It extends the validator with a rule for Vietnamese citizen identity numbers (the 9-digit CMND legacy scheme and/or the 12-digit CCCD scheme introduced in 2016, including the 6-digit province code, gender/century digit, and YYMMDD date-of-birth encoding).

Architecture fit: Fits cleanly into Laravel's validation subsystem. Expect either a ValidationRule object or a string-keyed rule registered via a service provider. Neither pattern introduces a new runtime dependency, queue, cache, or storage layer — the package is stateless and synchronous, so it does not alter our application architecture. This is an additive, opt-in capability.

Integration feasibility: Low. A patch-level version bump (3.2.0 → 3.2.1) with one added rule is a composer update plus wiring the rule into the relevant FormRequest classes. Realistic effort: under one developer day, plus QA and a localisation/compliance read-through. No config publishing, no migrations, no published assets should be required.

Technical risk:

• Semver discipline: a new rule is a feature but shipped as a patch. Harmless for a purely additively-used library, but it signals the maintainer may not use strict semver, which raises the cost of automated dependency-bump policies.
• Rule correctness: Vietnamese ID validation is not a pure checksum — it depends on province-code tables that are administratively revised, and on the historical CMND/CCCD transition. An unmaintained province table will produce false rejects on legitimate users.
• Retroactive application risk: if the rule is applied to an existing VN user base rather than only to new form submissions, previously accepted values may begin failing.
• False-accept exposure: if the rule is used as a KYC/AML control rather than a UX nicety, a permissive regex-style implementation creates a compliance gap that a TPM must not represent as verified identity.

Key questions:

1. Which schemes does the rule accept — CMND (9-digit), CCCD (12-digit), or both — and is there an explicit opt-in or migration flag?
2. Does it perform structural validation only, or does it validate province codes against a maintained dataset? Where does that dataset live and who updates it?
3. Does it implement the documented checksum, or is it regex-only?
4. Where is the rule registered — auto-discovered provider, or manual Validator::extend?
5. Are there tests/fixtures covering edge cases (leading zeros, pre-2016 IDs, malformed DOB segments)?
6. What is the maintainer's release cadence and issue-response history for other locale rules?
7. Does the rule return a translatable error message, or a hardcoded string we would need to override?

Integration Approach

Stack fit: Native to Laravel. Compatible with form requests, Validator::make, and inline $request->validate(). It composes with existing rule chains (required|string|vn_citizen_id|unique:users,id_number) and with bail. No conflict with our other validation packages expected, but confirm there is no duplicate rule-key collision if we already use a competing identity-rule library.

Migration path: Direct dependency bump. For a new release, no deprecations are in scope; the only migration concern is data, not code — existing stored ID values are unaffected because validation is write-path only unless we add a backfill or an admin-side re-validation job. Recommendation: do not retroactively validate existing records as part of this upgrade.

Compatibility: Verify PHP and Laravel version constraints from the package's composer.json against our current LTS. Check whether the rule is implemented against the modern ValidationRule/Rule contracts (Laravel 9+) or the legacy string signature; the latter can break under later framework versions. Confirm PHP 8.x support explicitly rather than inferring it from a patch bump.

Sequencing:

1. Sandbox install and inspect the rule source and its tests — this is a five-minute read and answers most of the technical-risk questions above.
2. Add the rule behind a config flag in the VN onboarding path only.
3. Wire into form requests for new VN registrations; leave legacy records untouched.
4. Ship to staging, run QA with a fixture set of real-format synthetic IDs (including legacy 9-digit and pre-2016 cases).
5. Production release with a feature flag; monitor validation-failure rates per field for the first two weeks before enforcing (non-nullable) behaviour.
6. Only after that, consider a backfill audit as a separate, unrelated initiative.

Operational Impact

Maintenance: Very low surface area — no infrastructure, no schema, no background processes. The real maintenance burden is indirect: tracking the package's future releases for province-table updates and framework compatibility. Assign ownership of that dependency bump to the team owning VN onboarding, not to a central platform team.

Support: Determine whether this is a single-maintainer community package or vendor-backed. For a compliance-adjacent validator used in a regulated market, single-maintainer status is a material risk that should be recorded in the risk register, with a documented exit path (fork the rule locally — it is small enough that this is cheap).

Scaling: Negligible. Validation is CPU-bound string work executed in-request; it will not appear in capacity planning. If applied to bulk imports, run it in a queued job rather than synchronously per row.

Failure modes:

• False reject (most likely): stale province-code data or an overly strict pattern blocking legitimate VN sign-ups. Detect via conversion-funnel monitoring on the ID field; mitigate with a feature flag and a manual-review fallback.
• False accept: permissive validation passing invalid IDs, creating downstream KYC rework or compliance findings. Mitigate by not treating this rule as an identity-verification control.
• Package abandonment: no updates to province data. Mitigate by vendoring the rule.
• Silent behaviour change: a future patch release altering rule semantics. Mitigate by pinning the version and reviewing diffs on bump.

Ramp-up: Minimal for engineers — a Laravel developer is productive in under an hour. The non-obvious ramp-up is on the business side: product, support, and compliance stakeholders need to understand that this rule validates format, not identity, and that a valid-format ID is not a verified citizen. Set that expectation explicitly before launch, or the team will inherit a support queue of users with edge-case documents and an overstated sense of compliance coverage.