README

Sedkiy Faker

A FakerPHP extension for generating culturally accurate, hyper-localized test data across 19 countries.

Why Sedkiy Faker?
Requirements
Installation
Quick Start
Usage
Supported Locales & Fields
Testing
Contributing
License

Why Sedkiy Faker?

Standard FakerPHP locale fallbacks often produce structurally invalid phone numbers, non-existent cities, and culturally mismatched honorifics. Sedkiy Faker fixes this at the container level, so fake() just works correctly out of the box.

Standard FakerPHP Fallbacks	Sedkiy Faker Localized Engine
Structurally invalid phone formats	Real ITU-T compliant mobile and landline numbers
Non-existent / generic city names	Authentic city and region catalogs per territory
Culturally mismatched name honorifics	Gender and region-specific honorifics (e.g., `Si`, `Lalla`)
Manual setup and provider overriding	Zero-configuration auto-extension into Laravel

Requirements

Requirement	Version
PHP	8.1+
Composer	Any recent version
Laravel	10, 11, or 12 (optional — not required for standalone use)

Installation

composer require sedkiy/faker --dev

Quick Start

use Sedkiy\Faker\SedkiyFaker;

$faker = SedkiyFaker::locale('ar_MA')->make();

$faker->name();         // "Mr. Youssef Alami"
$faker->city();         // "Casablanca"
$faker->phoneNumber();  // "+212 6 12 34 56 78"
$faker->postcode();     // "20000"
$faker->freeEmail();    // "youssef.alami@menara.ma"

That's it — no config files, no service provider setup required for standalone use.

Usage

Standalone PHP Usage

Instantiate a localized generator manually using the fluent SedkiyFaker factory:

use Sedkiy\Faker\SedkiyFaker;

$faker = SedkiyFaker::locale('ar_MA')->make();

$faker->name();
$faker->city();
$faker->phoneNumber();

Reproducible Outputs (Seeding)

Pass a seed to get deterministic output across test runs:

$faker = SedkiyFaker::locale('de_DE')->seed(1337)->make();

Chaining Custom Providers

Add your own providers on top without losing locale-specific behavior:

$faker = SedkiyFaker::locale('fr_FR')
    ->withProvider(\Faker\Provider\fr_FR\Text::class)
    ->make();

This also works with fully custom provider classes you write yourself — useful for fields Sedkiy Faker doesn't ship with (national ID formats, tax numbers, etc.).

Laravel Integration (Zero Code Changes)

Zero Code Pollution — there's no need to touch your existing factories or seeders. Sedkiy Faker hooks directly into Laravel's fake() helper and $this->faker property via container extenders.

Set your desired locale in .env:

FAKER_LOCALE=ar_MA
# or the package-specific override:
SEDKIY_FAKER_LOCALE=ar_MA

If omitted, it falls back to app.faker_locale in config/app.php, then to en_US.

Your existing factories now generate localized data automatically:

// database/factories/UserFactory.php

public function definition(): array
{
    return [
        'name'    => fake()->name(),          // "Youssef Alami"
        'address' => fake()->streetAddress(), // "Avenue Hassan II"
        'phone'   => fake()->phoneNumber(),   // "+212 6 12 34 56 78"
        'email'   => fake()->freeEmail(),     // "youssef@menara.ma"
    ];
}

Publishing the Config File (Optional)

php artisan vendor:publish --tag="sedkiy-faker-config"

Supported Locales & Fields

Each locale supports the Person, Address, Internet, and (MENA only) PhoneNumber providers. Commonly used methods per category:

Person — name(), firstName(), firstNameMale(), firstNameFemale(), lastName(), title(), titleMale(), titleFemale()
Address — city(), streetAddress(), address(), postcode(), state()
PhoneNumber (MENA locales) — phoneNumber(), mobileNumber()
Internet — email(), freeEmail(), userName(), domainName()

Note: Fields outside these categories (e.g. jobTitle(), url()) are not part of this package's localized data and will fall back to FakerPHP's generic/default provider output — verify with a quick test before relying on them in a specific locale.

MENA Region

Locale	Country	Providers
`ar_MA`	Morocco	Person, Address, PhoneNumber, Internet
`ar_DZ`	Algeria	Person, Address, PhoneNumber, Internet
`ar_TN`	Tunisia	Person, Address, PhoneNumber, Internet
`ar_EG`	Egypt	Person, Address, PhoneNumber, Internet
`ar_LY`	Libya	Person, Address, PhoneNumber, Internet
`ar_SA`	Saudi Arabia	Person, Address, PhoneNumber, Internet
`ar_LB`	Lebanon	Person, Address, PhoneNumber, Internet
`ar_JO`	Jordan	Person, Address, PhoneNumber, Internet

Europe & North America

Locale	Country	Providers
`fr_FR`	France	Person, Address, PhoneNumber
`de_DE`	Germany	Person, Address, PhoneNumber
`es_ES`	Spain	Person, Address, PhoneNumber
`it_IT`	Italy	Person, Address, PhoneNumber
`pt_PT`	Portugal	Person, Address, PhoneNumber
`en_GB`	United Kingdom	Person, Address, PhoneNumber
`nl_NL`	Netherlands	Person, Address, PhoneNumber
`nl_BE`	Belgium	Person, Address, PhoneNumber
`pl_PL`	Poland	Person, Address, PhoneNumber
`ro_RO`	Romania	Person, Address, PhoneNumber
`en_US`	United States	Person, Address, PhoneNumber

Testing

Tests are written with Pest PHP and validate reproducibility, ITU-T phone format compliance, postcode regex rules, and container extensions.

composer install
vendor/bin/pest

Contributing

Contributions that extend locale coverage are welcome:

Fork the repository and create a feature branch.
Follow code standards — format with PHP CS Fixer: composer run php-cs-fixer.
Ensure data integrity — new locale dictionaries need at least 30 real-world entries.
Add tests in tests/Providers/ for any new locale or field.
Open a Pull Request describing your changes.

License

Open-sourced under the MIT License.

sedkiy / faker

Maintainers

Package info

Statistics

Security