PHPackages                             chaoswey/taiwan-id-validator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. chaoswey/taiwan-id-validator

ActiveLibrary[Validation & Sanitization](/categories/validation)

chaoswey/taiwan-id-validator
============================

台灣身分證、統一編號驗證

1.0.0(6mo ago)309.2k5MITPHPPHP >=8.1

Since Apr 26Pushed 6mo agoCompare

[ Source](https://github.com/chaoswey/taiwan-id-validator)[ Packagist](https://packagist.org/packages/chaoswey/taiwan-id-validator)[ Docs](https://github.com/chaoswey/taiwan-id-validator)[ RSS](/packages/chaoswey-taiwan-id-validator/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (3)Used By (0)

Taiwan ID Validator
===================

[](#taiwan-id-validator)

一組 PHP / Laravel 共用的驗證工具，支援台灣營利事業統一編號、國民身分證、新舊式外來人口統一證號與常見證號格式。2025 版以策略模式重構，可依需求替換或擴充驗證器，同時保留舊有 API 以利升級。

特色
--

[](#特色)

- `isBan`：營利事業統一編號，新版預設（2023.04 後）並可選擇套用舊規則。
- `isIdCardNumber`：統一處理國民身分證、新／舊式外來人口統一證號，提供細緻的開關與族群限制。
- `isMobileBarcode`、`isDonationCode`、`isCitizenDigitalCertificate`、`isCreditCardNumberValid` 等常用格式驗證。
- Laravel Service Provider 內建驗證規則（含新舊命名），可直接於驗證器或 Request 使用。
- 以工廠模式封裝，各驗證器獨立成物件，易於繼承或覆寫。

安裝
--

[](#安裝)

```
composer require chaoswey/taiwan-id-validator
```

快速開始
----

[](#快速開始)

### Laravel Facade

[](#laravel-facade)

```
use Chaoswey\TaiwanIdValidator\Facades\TaiwanIdValidator;

TaiwanIdValidator::isBan('04595257');
TaiwanIdValidator::isBan('04595252', ['applyOldRules' => true]); // 舊版演算法

// IdCard 基礎用法
TaiwanIdValidator::isIdCardNumber('A123456789');
TaiwanIdValidator::isIdCardNumber('A800000014', [
    'nationalId' => false,
    'uiNumber' => [
        'oldFormat' => false,
        'newFormat' => [
            'foreignOrStateless' => true,
            'statelessResident' => false,
            'hkMacaoResident' => false,
            'mainlandChinaResident' => false,
        ],
    ],
]);
TaiwanIdValidator::isMobileBarcode('/AAA33AA');

// 更複雜的 IdCard 組合
TaiwanIdValidator::isIdCardNumber('AA00000009', ['scope' => 'resident-original']); // 僅舊式統一證號
TaiwanIdValidator::isIdCardNumber('A870000015', [
    'scope' => 'resident-new',
    'nationalId' => false,
    'uiNumber' => [
        'oldFormat' => false,
        'newFormat' => [
            'enabled' => true,
            'categories' => [
                'foreignOrStateless' => false,
                'statelessResident' => true,
                'hkMacaoResident' => false,
                'mainlandChinaResident' => false,
            ],
        ],
    ],
]);
TaiwanIdValidator::isIdCardNumber('A880000018', [
    'scope' => ['resident-new'],
    'uiNumber' => [
        'oldFormat' => false,
        'newFormat' => [
            'categories' => [
                'foreignOrStateless' => false,
                'statelessResident' => false,
                'hkMacaoResident' => true,
                'mainlandChinaResident' => false,
            ],
        ],
    ],
]);
TaiwanIdValidator::isIdCardNumber('A123456789', [
    'scope' => 'citizen|resident-original', // 同時允許某範圍
    'uiNumber' => ['newFormat' => false],
]);

TaiwanIdValidator::isDonationCode('10001');
TaiwanIdValidator::isCitizenDigitalCertificate('AB12345678901234');
TaiwanIdValidator::isCreditCardNumberValid('5105105105105100', ['checkIssuerRegexes' => true]);
```

### 純 PHP

[](#純-php)

```
use Chaoswey\TaiwanIdValidator\TaiwanIdValidator;

$validator = new TaiwanIdValidator();
$validator->isBan('12345675');
$validator->isIdCardNumber('AA00000009', ['scope' => 'resident-original']);
$validator->isIdCardNumber('A800000014', [
    'nationalId' => false,
    'uiNumber' => [
        'oldFormat' => false,
        'newFormat' => [
            'categories' => [
                'foreignOrStateless' => true,
                'statelessResident' => false,
                'hkMacaoResident' => false,
                'mainlandChinaResident' => false,
            ],
        ],
    ],
]);
$validator->isMobileBarcode('/+.-++..');
```

Laravel 驗證規則
------------

[](#laravel-驗證規則)

規則名稱說明範例`isBan`統一編號。參數：`old`/`oldRules` 套用舊演算法`isBan:old``isIdCardNumber`身分證/外來人口證號。支援複數參數（逗號分隔）。
`scope=a|b` 指定驗證範圍（詳見下方說明）。
`nationalId=false` 關閉身分證驗證。
`ui=true/false` 或 `uiOld=true`、`uiNew=false` 控制新舊格式。
`uiNewCategories=foreignOrStateless,statelessResident` 指定可接受族群。`isIdCardNumber:scope=citizen`,
`isIdCardNumber:nationalId=false,uiOld=false,uiNewCategories=hkMacaoResident`,
`isIdCardNumber:scope=resident-new,uiNewCategories=foreignOrStateless`,
`isIdCardNumber:scope=resident`,
`citizen,ui=false``isMobileBarcode`電子發票手機條碼-`isCitizenDigitalCertificate`自然人憑證-`isDonationCode`電子發票捐贈碼-`isCreditCard`信用卡號，參數加上 `issuer` 代表同時檢查發卡組織`isCreditCard:issuer`### 相容舊版規則

[](#相容舊版規則)

原有的規則名稱仍可使用（`isGUI`、`isNI`、`isRC`、`isNewRC`、`isOriginalRC`、`isCDC`、`isCellPhoneBarcode`、`isDonateCode`），內部已改呼叫新方法，建議逐步調整為新命名。

API 一覽
------

[](#api-一覽)

方法說明與選項`isBan(mixed $value, array $options = [])`驗證統一編號。`applyOldRules` 選項開啟舊演算法。`isIdCardNumber(mixed $value, array $options = [])`統一的身分證／外來人口證號驗證。選項：
- `scope`：字串或陣列（`citizen`、`resident-new`、`resident-original`、`resident`）。
- `nationalId`：布林，預設 `true`。
- `uiNumber.oldFormat`：布林，預設 `true`。
- `uiNumber.newFormat.enabled`：布林，預設 `true`。
- `uiNumber.newFormat.categories`：陣列，預設全部 `true`，可設定 `foreignOrStateless`、`statelessResident`、`hkMacaoResident`、`mainlandChinaResident`。`isMobileBarcode(mixed $value)`電子發票手機條碼。`isCitizenDigitalCertificate(mixed $value)`自然人憑證碼。`isDonationCode(mixed $value)`電子發票捐贈碼。`isCreditCardNumberValid(mixed $value, array $options = [])`信用卡卡號。`checkIssuerRegexes` 控制是否驗證發卡組織。> 舊版函式（例如 `isGuiNumberValid`、`isNationalIdentificationNumberValid` 等）仍可使用，但已標記為 `@deprecated`，會轉呼叫新 API。

### IdCard `scope` 與 `uiNumber` 參數說明

[](#idcard-scope-與-uinumber-參數說明)

- `scope`：指定允許驗證的證號類別，可使用單一值或 `|` 分隔的多值。
    - `citizen`：只驗證國民身分證字號（第一碼英文字母、第二碼 1 或 2）。
    - `resident-new`：只驗證新式外來人口/居留證號（第一碼英文字、第二碼 8 或 9）。
    - `resident-original`：只驗證舊式統一證號（前兩碼英文字，第二碼限 A-D）。
    - `resident`：同時允許新舊式外來人口證號。
- `nationalId`：布林值（預設 `true`），是否允許國民身分證。
- `uiNumber.oldFormat`：布林值（預設 `true`），是否允許舊式外來人口統一證號。
- `uiNumber.newFormat.enabled`：布林值（預設 `true`），控制新式統一證號是否驗證。
- `uiNumber.newFormat.categories`：陣列，用於限制新式統一證號的族群，鍵值如下（預設皆為 `true`）：
    - `foreignOrStateless`：一般外國人或無國籍人士（第 3 碼 0-6）。
    - `statelessResident`：無戶籍國民（第 3 碼 7）。
    - `hkMacaoResident`：香港／澳門居民（第 3 碼 8）。
    - `mainlandChinaResident`：大陸地區人民（第 3 碼 9）。

範例：

```
TaiwanIdValidator::isIdCardNumber('A800000014', [
    'nationalId' => false,
    'uiNumber' => [
        'oldFormat' => false,
        'newFormat' => [
            'enabled' => true,
            'categories' => [
                'foreignOrStateless' => true,
                'statelessResident' => false,
                'hkMacaoResident' => false,
                'mainlandChinaResident' => false,
            ],
        ],
    ],
]);
```

自訂驗證器
-----

[](#自訂驗證器)

每一種驗證皆為獨立類別（位於 `src/Validators`）。若需擴充，實作 `Chaoswey\TaiwanIdValidator\Contracts\ValidatorInterface` 後，可透過建構 `TaiwanIdValidator` 時注入自訂工廠，或註冊自己的 Service Provider 覆寫容器綁定。

```
use Chaoswey\TaiwanIdValidator\Factories\ValidatorFactory;
use Chaoswey\TaiwanIdValidator\TaiwanIdValidator;

$factory = new ValidatorFactory([
    'custom_ban' => App\Validators\MyBanValidator::class,
]);

$validator = new TaiwanIdValidator($factory);
```

升級指南
----

[](#升級指南)

- `isGuiNumberValid()`、更名為 `isBan()`；切換舊版演算法改使用 `['applyOldRules' => true]`。
- `isNationalIdentificationNumberValid()`、`isResidentCertificateNumberValid()`、`isNewResidentCertificateNumberValid()`、`isOriginalResidentCertificateNumberValid()` 合併為 `isIdCardNumber()`；可透過 `scope` 與 `uiNumber` 控制行為。
- Laravel 驗證規則提供新命名（`isBan`、`isIdCardNumber` 等），舊名仍可相容。

參考來源
----

[](#參考來源)

- [enylin/taiwan-id-validator](https://github.com/enylin/taiwan-id-validator)（原始 JS 實作）

###  Health Score

45

—

FairBetter than 92% of packages

Maintenance66

Regular maintenance activity

Popularity36

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~907 days

Total

2

Last Release

205d ago

Major Versions

0.1.0 → 1.0.02025-10-20

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3068634?v=4)[chaoswey](/maintainers/chaoswey)[@chaoswey](https://github.com/chaoswey)

---

Top Contributors

[![chaoswey](https://avatars.githubusercontent.com/u/3068634?v=4)](https://github.com/chaoswey "chaoswey (1 commits)")[![weya-chaoswey](https://avatars.githubusercontent.com/u/91188124?v=4)](https://github.com/weya-chaoswey "weya-chaoswey (1 commits)")

---

Tags

arccdccredit-carddonate-codegui-numberlaravelphptaiwantaiwan id validator

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/chaoswey-taiwan-id-validator/health.svg)

```
[![Health](https://phpackages.com/badges/chaoswey-taiwan-id-validator/health.svg)](https://phpackages.com/packages/chaoswey-taiwan-id-validator)
```

###  Alternatives

[webmozart/assert

Assertions to validate method input/output with nice error messages.

7.6k894.0M1.2k](/packages/webmozart-assert)[bensampo/laravel-enum

Simple, extensible and powerful enumeration implementation for Laravel.

2.0k15.9M104](/packages/bensampo-laravel-enum)[swaggest/json-schema

High definition PHP structures with JSON-schema based validation

48612.5M73](/packages/swaggest-json-schema)[stevebauman/purify

An HTML Purifier / Sanitizer for Laravel

5325.6M19](/packages/stevebauman-purify)[ashallendesign/laravel-config-validator

A package for validating your Laravel app's config.

217905.3k5](/packages/ashallendesign-laravel-config-validator)[crazybooot/base64-validation

Laravel validators for base64 encoded files

1341.9M8](/packages/crazybooot-base64-validation)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)