Axiom Laravel Package

Getting Started

• Install with Composer using the package’s documented command, then check the README for the rule table and supported Laravel versions.
• Look first at src/Rules, tests/Rules, and any published config/ file. The v3.2.1 addition is a new Vietnamese citizen rule, so start with that rule class and its tests to confirm expected input format.
• No migration or config publish is required for this release. Minimal first use case: validate a Vietnamese citizen ID on a KYC/onboarding form.

use Vendor\Package\Rules\VietnameseCitizenId;

public function rules(): array
{
    return [
        'citizen_id' => ['required', 'string', new VietnameseCitizenId()],
    ];
}

If the package registers string aliases, confirm the alias in the README before using 'vietnamese_citizen_id'; otherwise instantiate the rule object directly.

Implementation Patterns

• Use the rule object inside FormRequests for normal HTTP validation. Compose it with required, string, digits:12, and unique where appropriate.
• Apply conditionally when nationality is Vietnamese:

'citizen_id' => [
    'required',
    Rule::when($this->input('nationality') === 'VN', [new VietnameseCitizenId()]),
],

• Centralize reusable rule sets in a dedicated Rules class or custom request base class so the new rule is applied consistently across registration, profile update, and admin forms.
• Add custom messages through the FormRequest messages() method rather than editing package files.
• Test with PHPUnit/Pest datasets covering: valid 12-digit CCCD, invalid checksum/format, old 9-digit CMND, whitespace/hyphenated input, and non-numeric input. Reuse the package’s own fixtures where possible instead of guessing valid samples.
• For jobs or bulk imports, use Validator::make() with the same rule object so behavior matches HTTP validation.
• Treat new country rules as additive: keep the package updated, but pin a minor version if compliance requirements demand stable rule behavior.

Gotchas and Tips

• Vietnamese citizen IDs are typically 12-digit CCCD numbers; older 9-digit CMND numbers may not pass. Confirm the rule’s expected format before exposing it to users.
• Normalize input before validation if your business rules allow it — trim whitespace and strip spaces/hyphens — because the rule may expect a clean digit string.
• The rule validates format/checksum only; it does not prove the identity exists. Pair it with an authoritative verification service for high-assurance KYC.
• String-rule aliases can lag newly added rule objects behind the object API. If the alias is missing, use new VietnameseCitizenId().
• Check Laravel version compatibility in composer.json; validation-rule packages often support a range of Laravel releases but may not test every combination.
• Debug with Validator::make($data, $rules)->errors() in a tinker session or test rather than relying only on browser feedback.
• Extension point: wrap the package rule in your own rule to normalize input or add logging, rather than forking the package.
• v3.2.1 is additive and should not require code changes. Pin ^3.2 if you want the Vietnamese rule available consistently across deployments.