jontsa/national-identification-number

Parse national identification numbers.

1.0.1 2022-03-05 05:16 UTC

Requires

• php: ^7.4.0|^8.0

Requires (Dev)

• phpstan/phpstan: ^1.4.0
• phpunit/phpunit: ^9.0

MIT

• Joni Halme

• Personal id
• Social security number
• national identification number

README

This package can be used to parse, validate and format national personal identification numbers. In some countries these might be called social security numbers, national insurance numbers etc.

There are other similar packages available but some are not updated anymore, some do not work with newer PHP versions, some only support one country etc. This package was created to better suit our needs. It only supports limited set of countries but adding new countries should be easy if syntax is described somewhere.

Features

• Parse and validate national identifier string
• Returns object with known properties extracted from the identifier
• Supported countries
  • Austria
  • Estonia
  • Finland
  • Sweden both personal- and organization numbers
  • United Kingdom NI Number

Requirements

• PHP 7.4 or higher
• composer

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Open a command console, enter your project directory and execute:

$ composer require jontsa/national-identification-number

Usage

Parse and validate identity number:

use Jontsa\NationalIdentificationNumber\Exception\InvalidIdentifierExceptionInterface;
use Jontsa\NationalIdentificationNumber\Exception\InvalidSyntaxExceptionInterface;
use Jontsa\NationalIdentificationNumber\Exception\UnsupportedCountryException;
use Jontsa\NationalIdentificationNumber\Factory;
use Jontsa\NationalIdentificationNumber\IdentificationNumber\BirthDateAwareInterface;
use Jontsa\NationalIdentificationNumber\IdentificationNumber\GenderAwareInterface;

$country = 'FI';
$string = '150921A123A';
try {
    $identificationNumber = Factory::create($country, $string);
    echo "Yay, this is a valid personal identification number.\n";
    if ($identificationNumber instanceof BirthDateAwareInterface) {
        if ($identificationNumber instanceof GenderAwareInterface) {
            $pronoun = $identificationNumber->getGender() === GenderAwareInterface::GENDER_MALE ? 'He' : 'She';
        } else {
            $pronoun = 'Person'
        }
        echo $pronoun . " was born on " . $identificationNumber->getBirthDate()->format('Y-m-d') . "\n";
    }
} catch (UnsupportedCountryException $e) {
    echo 'Sorry but ' . $country . ' is not supported. Maybe you can create a ticket or PR in Github?';
} catch (InvalidSyntaxExceptionInterface|InvalidIdentifierExceptionInterface $e) {
    echo 'The supplied string was not a valid personal identification number';
}

Alternative method for parsing identity number for specific country:

use Jontsa\NationalIdentificationNumber\Exception\InvalidIdentifierExceptionInterface;
use Jontsa\NationalIdentificationNumber\Exception\InvalidSyntaxExceptionInterface;
use Jontsa\NationalIdentificationNumber\Factory;

try {
    $identificationNumber = Factory::FI('150921A123A');
    echo "Yay, this is a valid personal identification number.\n";
    echo 'Gender: ' . $identificationNumber->getGender() . "\n";
    echo 'Born: ' . $identificationNumber->getBirthDate() . "\n";
} catch (InvalidSyntaxExceptionInterface|InvalidIdentifierExceptionInterface $e) {
    echo 'The supplied string was not valid Finnish personal identification number';
}

Calculate checksum and format Finnish personal identity number:

use Jontsa\NationalIdentificationNumber\IdentificationNumber\FinnishIdentificationNumber;

$identificationNumber = new FinnishIdentificationNumber('19', '-', '79', '01', '31', '082');
echo 'Correct checksum: ' . $identificationNumber->getCheckSum() . "\n";
echo 'Formatted: ' . $identificationNumber->format() . "\n";

// output
// Correct checksum: U
// Formatted: 310179-082U