README

This PHP/Laravel Faker library generates valid South African ID numbers, adhering to the 13-digit format specified by the Department of Home Affairs. It is also able to validate RSA ID numbers, and provide information about the ID number holder.

The generated ID numbers include the date of birth, gender, citizenship status, and a checksum digit for validation.

Features

• Generates valid South African ID numbers.
• Supports male and female gender identification.
• Includes citizenship status (South African citizen or permanent resident).

Requirements

• PHP 7.4 or higher
• Laravel 9 or higher

Installation

Via Composer

composer require nonsapiens/south-african-id-number-faker

Usage (Generation)

With Faker

class UserFactory extends Factory
{
    /**
     * Define the model's default state.
     *
     * @return array<string, mixed>
     */
    public function definition(): array
    {
        return [
            'name' => $name,
            'email' => $this->faker->safeEmailAddress(),
            'rsa_id_number' => $this->faker->southAfricanIdNumber(),  # Completely random
            'email_verified_at' => Carbon::now(),
            'password' => bcrypt('12345'),
            'remember_token' => Str::random(10),
            'created_at' => Carbon::now(),
            'updated_at' => Carbon::now(),
            'last_accessed_at' => Carbon::now(),
            'is_active' => $this->faker->boolean(),
            'settings_json' => $this->faker->words(),
        ];
    }
}

You can also generate using:

Specified details

$this->faker->southAfricanIdNumber('1982-08-01', 'm');

Gender specific

$this->faker->southAfricanIdNumberFemale()

$this->faker->southAfricanIdNumberMale(Carbon::parse('1985-01-09'))

Using the helper class

use Illuminate\Support\Carbon;
use Nonsapiens\SouthAfricanIdNumberFaker;

// Example: Generate an ID for a male South African citizen born on 15 August 1995, using Carbon
$dateOfBirth = Carbon::createFromDate(1995, 8, 15);
$idNumber1 = RsaIdNumber::generateRsaIdNumber($dateOfBirth, 'm', true);

// Example: Generate for a female, random date of birth, non-citizen
$idNumber2 = RsaIdNumber::generateRsaIdNumber(null, 'f', false);

Usage (validation)

Laravel validation rule

You can validate incoming request data using the built-in rsaidnumber rule:

$request->validate([
    'rsaIdNumber' => 'required|string|rsaidnumber',
]);

If validation fails, Laravel will return the default message:

The rsaIdNumber must be a valid South African ID number.

You may customize this message in your localization files under validation.custom.rsaidnumber.

Using the helper class

$idNumber = new RsaIdNumber('8208015009088');     # This will also accept ID numbers with spaces
if ($idNumber->isValid()) {
    echo "This ID number is {$idNumber->gender()}";
} else {
    echo 'Invalid ID number';
}

Other validation features include:

$idNumber->dateOfBirth();
$idNumber->age();
$idNumber->isAdult();
$idNumber->isCitizen();
$idNumber->isPermanentResident();

You can also have the ID number formatted for easier reading:

$idNumber = new RsaIdNumber('7504220045086');
echo $idNumber->toNatural();     // Echoes as "750422 0045 08 6"

License

This library is open-source and available under the MIT License.

Contributions

Contributions, issues, and feature requests are welcome! Feel free to open a pull request or submit an issue on the repository.

Disclaimer

This library is for educational and testing purposes only. Do not use the generated ID numbers for illegal or unethical purposes.

About the author

Stuart Steedman is the CTO of Sebenza, a DNI company, operating out of Bryanston, South Africa. Stuart enjoys public speaking, and enjoys prototyping complex software in Laravel.