Mykad Laravel Package

Technical Evaluation

Architecture Fit

• Lightweight & Focused: The package is a niche utility for MyKad validation, parsing, and formatting, making it a low-overhead addition to Laravel applications requiring Malaysian ID handling (e.g., government services, HR systems, or regional e-commerce).
• Stateless & Self-Contained: No external dependencies (beyond Laravel core) or database requirements, aligning well with microservices or modular monoliths where ID validation is isolated.
• Validation-Centric: Ideal for form validation (e.g., Laravel Form Requests), API payload sanitization, or data migration pipelines where MyKad compliance is critical.
• Limited Business Logic: Does not handle authentication, storage, or workflows—complements (rather than replaces) existing systems like Laravel Fortify or Passport.

Integration Feasibility

• Laravel Native: Leverages Laravel’s service provider, facade, and validation rules patterns, ensuring seamless integration with:
  • Form Requests (validate() method).
  • Custom Validation Rules (MyKad::validate()).
  • Model Observers (e.g., pre-save parsing).
• Configurable: Published config allows state-code mappings to be overridden (e.g., for custom regional logic).
• No ORM Dependency: Works with Eloquent, Query Builder, or raw arrays, reducing coupling.

Technical Risk

Key Questions

1. Use Case Clarity:
   • Is this for user input validation (e.g., registration) or data processing (e.g., batch imports)?
   • Are there regulatory requirements (e.g., GDPR-like handling of PII)?
2. Error Handling:
   • How should invalid MyKads be logged/reported (e.g., custom exceptions vs. Laravel’s ValidationException)?
3. Extensibility:
   • Will future needs include MyPR (temporary IDs) or passport numbers? (Package is MyKad-only.)
4. Testing:
   • Are there fuzz test cases for malformed inputs (e.g., 123456-01-1234, A1234567890)?
5. Alternatives:
   • Could a custom validation rule (without the package) suffice for simpler needs?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Validation: Replace manual regex with MyKad::validate() in FormRequests or API Resources.
  • Parsing: Use MyKad::parse() to extract state, gender, DOB for business logic (e.g., age verification).
  • Formatting: Standardize MyKad display (e.g., 123456-01-1234 → 12-01-1234-5).
• Non-Laravel:
  • Standalone PHP: Works outside Laravel via require (but loses facade benefits).
  • APIs: Useful for sanitizing MyKad inputs in GraphQL (Relay) or REST endpoints.
• Frontend:
  • Pair with JavaScript validation (e.g., Vue/React hooks) for client-side UX.

Migration Path

1. Assessment Phase:
   • Audit existing MyKad handling (e.g., regex in controllers, manual parsing).
   • Identify pain points (e.g., false positives in validation).
2. Pilot Integration:
   • Replace one validation rule (e.g., in UserRegistrationRequest) with MyKad::validate().
   • Test with edge cases (expired IDs, foreign nationals).
3. Full Rollout:
   • Batch Update: Replace all MyKad logic in the codebase.
   • Deprecate Legacy: Phase out custom regex/parsing functions.
4. Post-Launch:
   • Monitor false rejection rates (e.g., via Sentry/Error Tracking).

Compatibility

Sequencing

1. Validation Layer:
   • Integrate MyKad::validate() into Form Requests first (lowest risk).
2. Parsing Layer:
   • Use MyKad::parse() in business logic (e.g., age/gender checks).
3. Formatting Layer:
   • Standardize output formats (e.g., for PDFs/API responses).
4. Error Handling:
   • Customize exception messages (e.g., MyKad::validate() → ValidationException).

Operational Impact

Maintenance

• Pros:
  • MIT License: No vendor lock-in; can fork if needed.
  • Minimal Boilerplate: Reduces custom validation code.
  • Config-Driven: State mappings can be updated without code changes.
• Cons:
  • Vendor Risk: Unmaintained package (last release Dec 2024). Plan for forking if issues arise.
  • State-Code Updates: Manual updates required if government changes state codes.
  • No Official Support: Debugging falls to internal teams.

Support

• Internal:
  • Document custom error cases (e.g., "How to handle MyKad reissues?").
  • Create runbooks for common issues (e.g., "MyKad validation fails for foreign IDs").
• External:
  • If offering public APIs, provide clear error codes (e.g., 422 with invalid_my_kad).
  • Consider community contributions (e.g., GitHub Issues for edge cases).

Scaling

• Performance:
  • Stateless: No DB/network calls; scales horizontally.
  • Regex Overhead: Benchmark with 10K+ requests/sec if used in high-throughput APIs.
• Horizontal Scaling:
  • No shared state; works in serverless (AWS Lambda) or containerized (Docker) setups.
• Cold Starts:
  • Minimal initialization; ideal for serverless PHP (e.g., Bref).

Failure Modes

Ramp-Up

• Onboarding:
  • 1-2 Hours: Basic validation integration.
  • Half-Day: Full parsing/formatting + error handling.
• Training:
  • Focus on when to use validate() vs. parse().
  • Document common pitfalls (e.g., expired IDs, foreign nationals).
• Tooling:
  • Add PHPStan/Psalm checks for