Mykad Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require fikrimastor/mykad
   

   No additional setup is required unless you need custom state mappings (publish config).

2. First Use Case: Validation

   use Fikrimastor\Mykad\Facades\Mykad;
   
   $isValid = Mykad::isValid('123456-01-5678'); // true/false
   

3. Where to Look First

   • Facade API: Fikrimastor\Mykad\Facades\Mykad (primary entry point).
   • Core Methods: isValid(), parse(), format(), getState().
   • Config: config('mykad.states-code') (published via vendor:publish).

Implementation Patterns

Core Workflows

1. Validation in Forms

use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'mykad' => 'required|mykad', // Uses package's validation rule
]);

• Custom Rule: The package registers mykad as a Laravel validation rule.

2. Parsing MyKad Data

$parsed = Mykad::parse('123456-01-5678');
// Returns:
// [
//   'number' => '123456',
//   'state' => 'Johor',
//   'district' => '01',
//   'birth_year' => '56',
//   'check_digit' => '8',
// ]

3. Formatting for Display

$formatted = Mykad::format('123456015678'); // '123456-01-5678'

4. State/District Lookups

$state = Mykad::getState('01'); // 'Johor'
$district = Mykad::getDistrict('123456-01-5678'); // '01'

5. Age Calculation

$age = Mykad::getAge('123456-01-5678'); // Age based on birth year (56)

Integration Tips

• Laravel Validation: Use the mykad rule in Form Requests or manually.
• Model Casting: Cast MyKad fields in Eloquent models:

  protected $casts = [
      'mykad_number' => MykadCast::class, // Hypothetical; extend package if needed
  ];
  

• API Responses: Format MyKad data before returning to clients:

  return response()->json(['mykad' => Mykad::format($user->mykad)]);
  

Gotchas and Tips

Pitfalls

1. False Positives in Validation

   • The package validates format (e.g., 123456-01-5678) but not the check digit logic.
   • Workaround: Implement custom validation for check digits if strict validation is needed.

2. State Code Ambiguity

   • Some states share codes (e.g., 01 for Johor and 01 for Kuala Lumpur in older MyKads).
   • Tip: Use Mykad::parse() to resolve ambiguity via full number parsing.

3. Birth Year Calculation

   • The birth year is derived from the last 2 digits of the MyKad number (e.g., 56 in 123456-01-5678).
   • Gotcha: Assumes 20XX century. Add logic to handle edge cases (e.g., 00 for 19XX).

4. Hyphen Sensitivity

   • The package expects hyphens (-) for parsing. Inputs like 123456015678 must be formatted first:

     Mykad::parse(Mykad::format('123456015678')); // Force hyphenation
     

Debugging

• Invalid Parsing: Check if the input matches the expected format (NNNNNN-DD-YYCC).

  Mykad::parse('invalid'); // Throws \InvalidArgumentException
  

• State Mismatch: Verify config('mykad.states-code') matches your use case (e.g., historical vs. current codes).

Extension Points

1. Custom State Mappings Override the published config to add/remove states:

   'states-code' => [
       '99' => 'Custom State', // Add new entries
   ],
   

2. Check Digit Validation Extend the package to validate the check digit (modulo 11 algorithm):

   // In a service or trait:
   public function isValidWithCheckDigit(string $mykad): bool {
       $parsed = Mykad::parse($mykad);
       $checkDigit = $parsed['check_digit'];
       $calculated = $this->calculateCheckDigit($parsed['number'] . $parsed['district'] . $parsed['birth_year']);
       return $checkDigit == $calculated;
   }
   

3. Age Calculation Enhancement Improve getAge() to handle century ambiguity:

   public function getAge(string $mykad): int {
       $birthYear = Mykad::parse($mykad)['birth_year'];
       $currentYear = now()->year;
       return $birthYear >= 50 ? $currentYear - 1900 - $birthYear : $currentYear - 2000 - $birthYear;
   }
   

4. Validation Rule Customization Register a custom rule in AppServiceProvider:

   use Fikrimastor\Mykad\Rules\Mykad as MykadRule;
   
   Validator::extend('strict_mykad', function ($attribute, $value, $parameters) {
       return (new MykadRule)->passes('strict', $value);
   });