lil-pecky / random-person-generator
Requires
- php: ^8.1
Requires (Dev)
- pestphp/pest: ^2.3
This package is auto-updated.
Last update: 2024-06-04 16:02:10 UTC
README
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.
Getting started
Installation
This package requires PHP >= 8.1.
composer require lil-pecky/random-person-generator
Usage
There's two ways to instantiate a Generator instance;
Providing a specific locale to the factory
use LilPecky\RandomPersonGenerator\Factory; use LilPecky\RandomPersonGenerator\Locale; // the provided locale is required $locale = Locale::create('nl_NL'); $generator = Factory::create($locale);
Randomising the locale, providing an optional language
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.
Generating a person, or multiple people
$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);
Available methods
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
Source data
The names for each language/country have been generated using ChatGPT, and have been supplemented by FakerPHP names whenever possible.
Contributing
Adding names to locales
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
Adding names to a specific locale's JSON 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.
Adding names to a specific locale's Name.php
file
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 new locales
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
Adding new languages
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'
).