README

South African ID for PHP

A self-validating value object encapsulating a South African government-issued personal identification number, for PHP.

A South African government-issued identity number consists of 13 digits and the following segments:

birth date: the first 6 digits represent the person's date of birth in the format yymmdd.
gender: the next 4 digits indicate that the person is male if the value is 5000 or above; otherwise, female.
citizenship: the next single digit shows the person's citizenship status: 0 for a citizen, 1 for a permanent resident.
race: the next single digit was historically used to indicate the person's race.
check digit: the last digit is used to validate the entire number, to protect against typing errors. It is calculated with the Luhn Algorithm.

Install

Use Composer to install the package.

composer require spoorsny/south-african-id

Usage

The value object can be instantiated by passing a string to its constructor.

use Spoorsny\ValueObjects\SouthAfricanId;

$idNumber = new SouthAfricanId('9308062469083');

If the string argument is not in the valid format, an InvalidArgumentException with a message indicative of the type of error, will be thrown.

The value object can used in places where strings are used, because it implements the Stringable interface. For example, a value object can be instantiated by passing another instance to its constructor.

$idNumber1 = new SouthAfricanId('4608162219097');
$idNumber2 = new SouthAfricanId($idNumber1);

Note

The value object always formats the identity number with a single space between the date segment and the gender segment, and a single space between the gender segment and the citizenship segment.

It can be used with the strval() function and echo statement.

$idNumber = new SouthAfricanId('4608162219097');
strval($idNumber); // Evaluates to '460816 2219 097'.
echo $idNumber;    // Prints '460816 2219 097'.

Different instances of the class can be checked for equality with the equals() method.

$idNumber1 = new SouthAfricanId('4608162219097');
$idNumber2 = new SouthAfricanId('4608162219097');
$idNumber3 = new SouthAfricanId('8202277454090');

$idNumber1->equals($idNumber2); // true
$idNumber1->equals($idNumber3); // false

Even though the identity number starts with the person's birth date, it cannot be used to compare whether one person is older than another. This is due to the century portion being missing from the date.

Useful information encoded in the identity number can be extracted, for example:

$idNumber->birthMonth();
$idNumber->birthDay();

$idNumber->isFemale();
$idNumber->isMale();

$idNumber->isCitizen();
$idNumber->isPermanentResident();

The different segments of the identity number can be extracted from the value object as follows:

$idNumber->dateSegment();
$idNumber->genderSegment();
$idNumber->citizenshipSegment();
$idNumber->raceSegment();
$idNumber->checksumSegment();

Contributing

To contribute to the package, see the Contributing Guide.

License

This file is part of package spoorsny/south-african-id.

Package spoorsny/south-african-id is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Package spoorsny/south-african-id is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with package spoorsny/south-african-id. If not, see https://www.gnu.org/licenses/.

For a copy of the license, see the LICENSE file in this repository.

spoorsny / south-african-id

Maintainers

Details