turahe/number-validator

identification number validator

v1.0.0 2025-08-07 15:49 UTC

Requires

• php: ^8.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.38
• phpunit/phpunit: ^12.0

MIT

• Nur Wachid

• validator
• nik
• kk

README

A high-performance PHP package for validating and parsing Indonesian identity numbers (NIK and KK) with PHP 8.4 features and optimized performance.

🚀 Features

• NIK (Nomor Induk Kependudukan) validation and parsing
• KK (Kartu Keluarga) validation and parsing
• PHP 8.4 optimized with modern features
• High Performance with intelligent caching
• Offline Operation - no internet connection required
• Comprehensive Data - age, gender, zodiac, address, postal code
• Type Safety with strict type declarations
• Error Handling with detailed validation messages

📦 Installation

composer require turahe/number-validator

🎯 Quick Start

NIK Validation

<?php
use Turahe\Validator\NIK;

$nik = NIK::set('3273012501990001');
$result = $nik->parse();

if ($result->valid) {
    echo "Gender: " . $result->gender . "\n";
    echo "Born: " . $result->born->full . "\n";
    echo "Age: " . $result->age->year . " years\n";
    echo "Zodiac: " . $result->zodiac . "\n";
    echo "Province: " . $result->address->province . "\n";
    echo "City: " . $result->address->city . "\n";
    echo "Sub-district: " . $result->address->subDistrict . "\n";
    echo "Postal Code: " . $result->postalCode . "\n";
    echo "Unique Code: " . $result->uniqueCode . "\n";
}

KK Validation

<?php
use Turahe\Validator\KK;

$kk = KK::set('3273012501990001');
$result = $kk->parse();

if ($result->valid) {
    echo "Formatted: " . $kk->getFormattedNumber() . "\n";
    echo "Province: " . $result->address->province . "\n";
    echo "City: " . $result->address->city . "\n";
    echo "Sub-district: " . $result->address->subDistrict . "\n";
    echo "Postal Code: " . $result->postalCode . "\n";
}

🔧 Advanced Usage

Error Handling

<?php
use Turahe\Validator\NIK;

try {
    $nik = NIK::set('123456789012345'); // Too short
} catch (\InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

// Get detailed validation errors
$nik = NIK::set('1234567890123456'); // Valid format but invalid data
$errors = $nik->getValidationErrors();
print_r($errors);

Array Output

<?php
use Turahe\Validator\NIK;

$nik = NIK::set('3273012501990001');
$array = $nik->toArray();

echo json_encode($array, JSON_PRETTY_PRINT);

Type Safety

<?php
use Turahe\Validator\NIK;

// Both string and integer inputs work
$nik1 = NIK::set('3273012501990001');  // string
$nik2 = NIK::set(3273012501990001);    // integer

⚡ Performance Optimizations

Caching System

• Intelligent caching for frequently accessed data
• 13.8x faster performance on cached vs non-cached calls
• Memory-efficient caching strategy

String Operations

• Direct character access instead of substr()
• 2.6x faster string operations
• Optimized zodiac calculation with early returns

Memory Management

• Readonly properties for immutability
• Efficient object lifecycle management
• Static caching for current year calculation

🛡️ PHP 8.4 Features

• Readonly Properties: public readonly string $number
• Constructor Property Promotion: Simplified constructors
• Union Types: string|int for flexible input
• Null Coalescing Assignment: ??= operator
• Improved Type Declarations: Better type safety
• Early Returns: Optimized control flow

📊 Performance Benchmarks

Operation	Time	Memory
NIK Creation	~2.5ms	~783KB
NIK Parsing	~0.1ms	~4KB
KK Creation	~2.1ms	~739KB
KK Parsing	~0.02ms	~1KB
1000 NIK Operations	~1.5s	Optimized
1000 KK Operations	~1.5s	Optimized

🧪 Testing

Run the comprehensive test suite:

./vendor/bin/phpunit

All 63 tests pass with 100% coverage.

📁 Project Structure

number-validator/
├── src/
│   ├── Base.php          # Abstract base class with optimizations
│   ├── NIK.php           # NIK validator with caching
│   ├── KK.php            # KK validator with formatting
│   └── assets/
│       └── wilayah.json  # Location data
├── tests/
│   ├── BaseTest.php      # Base class tests
│   ├── NIKTest.php       # NIK validation tests
│   └── KKTest.php        # KK validation tests
├── example.php           # Performance demonstration
└── composer.json         # Dependencies

🔍 API Reference

NIK Class

Methods

• set(string|int $number): self - Create NIK instance
• parse(): object - Parse and validate NIK data
• validate(): bool - Check if NIK is valid
• getValidationErrors(): array - Get detailed error messages
• toArray(): array - Get data as array
• getGender(): string - Get gender (LAKI-LAKI/PEREMPUAN)
• getBornDate(): object - Get birth date information
• getAge(): object - Get age calculation
• getZodiac(): string - Get zodiac sign
• getProvince(): ?string - Get province name
• getCity(): ?string - Get city name
• getSubDistrict(): ?string - Get sub-district name
• getPostalCode(): ?string - Get postal code

KK Class

Methods

• set(string|int $number): self - Create KK instance
• parse(): object - Parse and validate KK data
• validate(): bool - Check if KK is valid
• getValidationErrors(): array - Get detailed error messages
• toArray(): array - Get data as array
• getFormattedNumber(): string - Get formatted KK number
• getRawNumber(): string - Get raw KK number
• getProvince(): ?string - Get province name
• getCity(): ?string - Get city name
• getSubDistrict(): ?string - Get sub-district name
• getPostalCode(): ?string - Get postal code

🚀 Performance Tips

1. Reuse Instances: Create validator once and reuse for multiple operations
2. Caching Benefits: Subsequent calls to getBornDate(), getAge(), etc. are cached
3. Type Safety: Use union types for flexible input handling
4. Error Handling: Always check $result->valid before accessing data

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Indonesian government for the NIK and KK number format specifications
• PHP community for the excellent 8.4 features
• All contributors who helped optimize this package

Built with ❤️ and optimized for PHP 8.4+