README

一个简单的马来西亚身份证号码（MyKAD、MyKID、MyKAS、MyPR、MyTentera）解析器和验证器。

安装

composer require my-gov/myjpn

基本用法

使用 MyKAD 解析器从给定的身份证号码中检索基本信息。

require 'vendor/autoload.php';

use Exception;
use MyGOV\MyJPN\Exceptions\InvalidMyKADBirthdateException;
use MyGOV\MyJPN\Exceptions\InvalidMyKADBirthplaceCodeException;
use MyGOV\MyJPN\Exceptions\InvalidMyKADCharactersException;
use MyGOV\MyJPN\Exceptions\InvalidMyKADLengthException;
use MyGOV\MyJPN\MyKAD;

try {
    $idNo = '980524-14-2347';
    $idNo = '980524 14 2347';
    $idNo = '980524142347';

    $myKad = MyKAD::parse($idNo);

    if ($myKad->isValid()) {
        echo $myKad;                        // 980524142347
        echo $myKad->formal();              // 980524-14-2347
        echo $myKad->formal(false);         // 980524142347
        echo $myKad->getSpecialNumber();    // 2347

        // Gender information. For some early batch of identity number, the gender is unknown.
        echo $myKad->isMale() ? 'Male' : 'Female';      // Male
        echo $myKad->isFemale() ? 'Female' : 'Male';    // Male

        // Place of birth information
        echo $myKad->getBirthplaceCode();   // 14
        echo $myKad->getState();            // Wilayah Persekutuan (Kuala Lumpur)
        echo $myKad->getCountry();          // Malaysia

        // Age information
        echo $myKad->getBirthDate()->format('Y-m-d');   // 1998-05-24
        echo $myKad->getAge();              // 26
        echo $myKad->getActualAge();        // 26 years 2 months 4 days
        echo $myKad->getAgeOn(date_create('2 years ago'));      // 24
        echo $myKad->getActualAge(date_create('last year'));    // 25 years 2 months 4 days
        $myKad->isOver(12) // true. Check is over 12 years old?
        $myKad->isOver(18) // true. Check is over 18 years old?

        // Age group.
        echo $myKad->getAgeGroup(); // Adult.
        $myKad->isChildren();       // false
        $myKad->isYouth();          // false
        $myKad->isAdult();          // true
        $myKad->isOldAdult();       // false
        $myKad->isSeniorCitizen();  // false
    }
} catch (InvalidMyKADLengthException | InvalidMyKADBirthplaceCodeException | InvalidMyKADBirthdateException | InvalidMyKADCharactersException | Exception $throwable) {
    echo $throwable->getMessage();
}

关闭异常

将 exception 设置为 false 以禁用 Exceptions

require 'vendor/autoload.php';

use MyGOV\MyJPN\MyKAD;

$myKad = MyKAD::parse('980524-14-2347', exception: false);

if ($myKad->isValid()) {
    echo $myKad->getBirthplaceCode();   // 14
    echo $myKad->getState();            // Wilayah Persekutuan (Kuala Lumpur)
} else {
    echo $myKad->getBirtplaceCode();   // null
    echo $myKad->getState();            // null
}

开启身份号码提取

从给定的字符串中提取身份号码。

require 'vendor/autoload.php';

use MyGOV\MyJPN\MyKAD;

$myKad = MyKAD::parse('John Doe (640329-10-7061)', extraction: true);

if ($myKad->isValid()) {
    echo $myKad->getBirthplaceCode();   // 10
    echo $myKad->getState();            // Selangor
} else {
    echo $myKad->getBirtplaceCode();   // null
    echo $myKad->getState();            // null
}

处理百岁老人

默认情况下，MyKAD 解析器只能处理100岁以下的出生日期。启用 isElderLy 以处理超过100岁的出生日期。

$myKad = MyKAD::parse('200618-14-2123')
$myKad->getBirthDate()->format('Y-m-d'); // 2020-06-18
$myKad->getAge(); // 4, assume this year is 2024.

$myKad = MyKAD::parse('200618-14-2123', isElderly: true)    // Enable is elderly.
$myKad->getBirthDate()->format('Y-m-d'); // 1920-06-18
$myKad->getAge(); // 104

更改显示语言

有3种语言：英语（en）、马来语（ms）、中文（zh-cn）。默认语言是英语（en）。

MyKAD::parse('200618-14-2123')->getState();                    // output: Federal Territory (Kuala Lumpur)
MyKAD::parse('200618-14-2123', language: 'ms')->getState();    // output: Wilayah Persekutuan (Kuala Lumpur)
MyKAD::parse('200618-14-2123', language: 'zh-cn')->getState(); // output: 联邦直辖区 (吉隆坡)

MyKAD 身份证号码生成器

生成一个随机身份证号码。

$myKad = MyKAD::make();
echo $myKad->formal();  // 980524-14-2347

为特定的出生日期生成一个身份证号码。

$myKad = MyKAD::make(date_create_from_format('Y-m-d', '2021-10-31'));
echo $myKad;            // 211031142347
echo $myKad->formal();  // 211031-14-2347

为特定的性别生成一个身份证号码。

$myKad = MyKAD::make(male: true); // generate `male` identity number only
echo $myKad->formal();      // 980524-14-2345
echo $myKad->isMale();      // true
echo $myKad->isFemale();    // false

$myKad = MyKAD::make(male: false); // generate `female` identity number only
echo $myKad->formal();      // 210314-10-1348
echo $myKad->isMale();      // false
echo $myKad->isFemale();    // true

为特定的出生地生成一个身份证号码。

$myKad = MyKAD::make(birthplaceCode: '10');
echo $myKad->formal();  // 980524-10-2347

$myKad = MyKAD::make(birthplaceCode: '82');
echo $myKad->formal();  // 010522-82-2588

// ensure generated identity number from Malaysia only.
$myKad = MyKAD::make(birthplaceCode: 'local');
echo $myKad->formal();    // 010522-02-2588
echo $myKad->getState();  // output: Kedah.

Laravel 验证中的使用

简单验证器

<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;
use MyGOV\MyJPN\MyKAD;

class MyKadValidator implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        try {
            if (!MyKAD::parse($value)->isValid()) {
                $fail('The :attribute is invalid.');
            }
        } catch (InvalidMyKADCharactersException $e) {
            $fail('Invalid characters.')
        } catch (InvalidMyKADLengthException $e) {
            $fail('Invalid length.')
        } catch (InvalidMyKADBirthplaceCodeException $e) {
            $fail('Invalid birth place code.')
        } catch (InvalidMyKADBirthdateException $e) {
            $fail('Invalid birthday.')
        }
    }
}

...

$request->validate([
    'id_no' => ['required', 'string', new MyKadValidator()],
]);

或者，一个简单的自定义规则。

use Illuminate\Support\Facades\Validator;
use Closure;
use MyGOV\MyJPN\MyKAD;

$validator = Validator::make($request->all(), [
    'id_no' => [
        'required',
        function (string $attribute, mixed $value, Closure $fail) {
            if (!MyKAD::parse($value, exception: false)->isValid()) {
                $fail("The {$attribute} is invalid.");
            }
        },
    ],
]);

许可证

Simsoft MyGOV/MyJPN 采用 MIT 许可证授权。有关详细信息，请参阅 LICENSE 文件。

my-gov / myjpn

维护者

详细信息