This package allows you to generate people with random names, birthdays and country of birth. The country of birth can either be completely random, or based on a provided language.
This package has been developed to fit a very specific use case, but since a list of random names can be useful for many projects, I decided to publish it.
This package is heavily influenced/inspired by FakerPHP.
This package requires PHP >= 8.1.
composer require lil-pecky/random-person-generator
There's two ways to instantiate a Generator instance;
use LilPecky\RandomPersonGenerator\Factory;
use LilPecky\RandomPersonGenerator\Locale;
// the provided locale is required
$locale = Locale::create('nl_NL');
$generator = Factory::create($locale);
use LilPecky\RandomPersonGenerator\Factory;
// generator for a completely random locale (en_GB, fr_FR, pt_BR, ...)
$generator = Factory::createWithRandomLocale();
// generator for a random locale within a specific language (nl_BE or nl_NL)
$generator = Factory::createWithRandomLocale('nl');
In both cases, the provided language must be present in the
LilPecky\RandomPersonGenerator\Languages::LANGUAGES
array, an exception will be thrown if an invalid language has been provided.
$locale = Locale::create('nl_NL');
$generator = Factory::create($locale);
$amount = new Amount(10);
$startDate = '2013-01-01';
$endDate = '2023-01-01';
$gender = Gender::FEMALE;
// generates a single Dutch person, with a male given name and date of birth between $startDate and $endDate
$person = $generator->person($startDate, $endDate, $gender);
// generates 10 Dutch people, each with a male given name and date of birth between $startDate and $endDate
$people = $generator->people($amount, $startDate, $endDate, $generator);
$people = $generator->persons($amount, $startDate, $endDate, $generator);
As this package has mainly been written to fit a very specific use case, the amount of available methods is limited;
require_once 'vendor/autoload.php';
$locale = Locale::create('nl_NL');
$generator = Factory::create($locale);
// generates a random date between two bounds.
// if no start date is provided, it defaults to now - 30 years. Can also be a DateTimeImmutable object
// if no end date is provided, it defaults to now. Can also be a DateTimeImmutable object
$generator->dateBetween('2013-01-01', '2023-01-01');
// generates a random male Dutch given name
// if no gender is provided, it defaults to Gender::MALE
$generator->givenName(Gender::MALE);
// generates a random Dutch family name
$generator->familyName();
Some languages, like Icelandic, have gendered last names, so an optional gender can be provided to the familyName
method
$locale = Locale::create('is_IS');
$generator = Factory::create($locale);
echo $generator->familyName(Gender::FEMALE);
// Eiðsdóttir
echo $generator->familyName(Gender::MALE);
// Þorfinnsson
The names for each language/country have been generated using ChatGPT, and have been supplemented by FakerPHP names whenever possible.
There are two ways of adding names;
- adding them to a specific locale's JSON file
- adding them to a specific locale's
Name.php
file
To add names to a locale's JSON file, open the locale's file in the data
directory and add names to the appropriate
types (male
& female
for given names, family
, family_male
& family_female
for given names, middle
for middle
names).
Afterwards, run
php scripts/generate-php-from-json.php
to add the newly added names to the appropriate PHP files.
To add names to a locale's Name.php
file, open that file in the src/Providers/{locale}
directory and add the names
to the appropriate properties.
Afterwards, run
php scripts/generate-json-from-php.php
to add the newly added names to the appropriate JSON files.
Adding a new locale is pretty simply. Create a new directory in the src/Providers
directory in the correct
format (ab_CD
), and in the new directory create a Name.php
file.
The new Name.php
file must extend
LilPecky\RandomPersonGenerator\Providers\Name::class
If the locale you've added a locale for which no language exists yet (for example, af_ZA for Afrikaans/South Africa), it would be appreciated if you add the new language to the
LilPecky\RandomPersonGenerator\Languages::LANGUAGES
array, with the ISO 639-1 language code as key and the language name as
value (for example, 'af' => 'Afrikaans'
).