Faker

https://github.com/fakerphp/faker
Admin
Faker is a PHP library that generates fake data for bootstrapping databases, creating test fixtures,...
Tokens:53,384
Snippets:470
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example usage of getFormatters()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Shows usage of Documentor to enumerate formatters and their examples. It prints the provider class and each signature-to-example mapping, but stops after the first provider. The example output is commented out of the code block.

```php
use Faker\Documentor;
use Faker\Factory;

$doc = (new Documentor(Factory::create()))->getFormatters();

foreach ($doc as $providerClass => $formatters) {
    echo $providerClass, "\n";
    foreach ($formatters as $signature => $example) {
        echo "  ", $signature, "  =>  ", $example, "\n";
    }
    break; // only the first provider
}

// Faker\Provider\Address
//   citySuffix()  =>  'town'
//   streetSuffix()  =>  'Street'
//   ...

```

--------------------------------

### format() usage examples

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Shows how to call formatters directly, with arguments, and via extension-direct call.

```php
$faker->format('name');                  // same as $faker->name()
$faker->format('numberBetween', [1, 10]);
$faker->format('Faker\Core\Barcode->ean13');  // extension-direct call
```

--------------------------------

### seed() usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Shows how to seed the generator to produce identical output for the same seed.

```php
$faker = Faker\Factory::create();
$faker->seed(1234);
$a = $faker->name();
$faker->seed(1234);
$b = $faker->name();   // $a === $b
```

--------------------------------

### Install Faker with Composer

Source: https://github.com/fakerphp/faker/blob/2.0/README.md

Install the fakerphp/faker package using Composer. Requires PHP >= 7.4.

```shell
composer require fakerphp/faker
```

--------------------------------

### Full Faker usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Complete example of creating a Faker instance with 'en_GB' locale, seeding, and generating a user array with name, email, phone, IBAN, date, and unique tags. Also demonstrates catching an InvalidArgumentException for an unknown format.

```php
use Faker\Factory;

$faker = Factory::create('en_GB');
$faker->seed(2024);

$user = [
    'name'  => $faker->name('male'),
    'email' => $faker->safeEmail(),
    'phone' => $faker->phoneNumber(),
    'iban'  => $faker->iban('GB'),
    'since' => $faker->dateTimeBetween('-2 years', 'now')->format('Y-m-d'),
    'tags'  => $faker->unique()->randomElements(['php', 'api', 'docs'], 2),
];

try {
    $faker->format('nope');
} catch (\InvalidArgumentException $e) {
    // "Unknown format "nope""
}
```

--------------------------------

### parse() usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Shows how to parse a template string with multiple tokens.

```php
echo $faker->parse('{{titleMale}} {{firstNameMale}} {{lastName}} @ {{freeEmailDomain}}');
```

--------------------------------

### Usage example for Faker\Core\Color

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-color.md

Shows how to instantiate Color directly and use it, plus the recommended way via the Faker generator.

```php
use Faker\Core\Color;
use Faker\Core\Number;

$color = new Color(new Number());

// Basic
echo $color->hexColor();        // '#8c2a7f'
echo $color->rgbaCssColor();    // 'rgba(12,200,50,0.34)'
echo $color->safeColorName();   // 'navy'

// Through the generator (recommended)
$faker = Faker\Factory::create();
echo $faker->format('Faker\Core\Color->hslColor');  // '207,61,9'
```

--------------------------------

### Extension-backed convenience methods usage

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Shows example calls to numberBetween, semver, bloodGroup, and ean13.

```php
echo $faker->numberBetween(1, 6);   // 1..6
echo $faker->semver(true, true);    // e.g. 2.4.1-beta.3+abc1234
echo $faker->bloodGroup();          // e.g. 'AB+'
echo $faker->ean13();               // e.g. '4006381333931'
```

--------------------------------

### randomFloat usage examples

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-number.md

Two example calls to randomFloat: one with explicit decimals and bounds, one with defaults.

```php
$f = $faker->randomFloat(2, 1.5, 9.5);    // e.g. 4.73
$f = $faker->randomFloat();               // e.g. 48.8932
```

--------------------------------

### Usage example for Faker\ChanceGenerator via optional()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/proxy-generators.md

Shows how to use the optional() method to create a ChanceGenerator. The first example gives a 30% chance of a phone number, otherwise null. The second uses a non-null default and a 5% chance, mostly returning 'unknown'.

```php
$faker = Faker\Factory::create();

// Basic: 30% chance of a phone number, otherwise null
$maybe = $faker->optional(0.3)->phoneNumber();

// Non-trivial: non-null default
echo $faker->optional(0.05, 'unknown')->city();   // mostly 'unknown'
```

--------------------------------

### Coordinates usage example (not registered)

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Attempts to use Coordinates via ext, but throws ExtensionNotFound because it is not in the default container.

```php
$faker = Faker\Factory::create();
$c = $faker->ext(\Faker\Core\Coordinates::class);   // not in default container! — throws ExtensionNotFound
```

--------------------------------

### Usage example for semver()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Shows how to use the semver() method through the Faker factory. The first call returns a basic version like '2.4.1', and the second call with both flags enabled returns a pre-release with build metadata like '0.7.99-beta.42+20240801120000'.

```php
$faker = Faker\Factory::create();
echo $faker->semver();            // '2.4.1'  (Generator::semver forwards here)
echo $faker->semver(true, true);  // '0.7.99-beta.42+20240801120000'
```

--------------------------------

### Usage example for valid() with basic and retry exhaustion

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/proxy-generators.md

Shows how to use valid() to generate only even digits, and how to catch OverflowException when no valid value is found after retries. The example uses a validator that always returns false to trigger the exception.

```php
$faker = Faker\Factory::create();

// Basic: only Fibonacci-safe digits
$faker->valid(fn ($d) => $d % 2 === 0)->randomDigit();   // 0, 2, 4, 6, 8

// Non-trivial: validator on a composite value + retry exhaustion
try {
    $faker->valid(fn ($v) => $v === 'impossible', 3)->name();
} catch (\OverflowException $e) {
    // valid value could not be found
}
```

--------------------------------

### File usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Demonstrates generating a random MIME type, file extension, and file path using the Faker factory. Note that filePath creates a real temporary file on disk.

```php
$faker = Faker\Factory::create();
echo $faker->mimeType();        // 'application/json'
echo $faker->fileExtension();   // 'png'
echo $faker->filePath();        // '/tmp/fakerAb12Cd34'  (creates the file on disk)
```

--------------------------------

### randomDigit usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-number.md

Example call to randomDigit, returning a digit like '7'.

```php
$d = $faker->randomDigit();   // '7'
```

--------------------------------

### Uuid usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Demonstrates generating a UUID version 3 using the Faker factory and the UuidExtension. Also shows a generator convenience format.

```php
$faker = Faker\Factory::create();
echo $faker->ext(\Faker\Extension\UuidExtension::class)->uuid3();   // v3, not v4
// generator convenience: $faker->format('Faker\Core\Uuid->uuid3')
```

--------------------------------

### Install Rector for Automated Refactoring

Source: https://github.com/fakerphp/faker/blob/2.0/README.md

Install the rector/rector package as a dev dependency to automate refactoring of deprecated Faker properties to methods.

```bash
composer require --dev rector/rector
```

--------------------------------

### Barcode usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Example usage of the Barcode extension: creating a Faker instance, generating an EAN-13 barcode, and using the format string to call isbn10.

```php
$faker = Faker\Factory::create();
echo $faker->ean13();                       // '4006381333931'
echo $faker->format('Faker\Core\Barcode->isbn10');
```

--------------------------------

### File class method signatures

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Shows the public method signatures for mimeType, extension, and filePath, with their source locations and example return values.

```php
public function mimeType(): string    // src/Core/File.php:548  — random key, e.g. 'video/avi'
public function extension(): string   // src/Core/File.php:553  — random value (flattens arrays), e.g. 'avi'
public function filePath(): string    // src/Core/File.php:560  — tempnam(sys_get_temp_dir(), 'faker')
```

--------------------------------

### Using ext() with NumberExtension and handling missing extension

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Example usage of ext() to retrieve a NumberExtension and call numberBetween(), plus a try-catch for ExtensionNotFound when the id is not registered.

```php
$number = $faker->ext(\Faker\Extension\NumberExtension::class);
echo $number->numberBetween(1, 6);

try {
    $faker->ext('App\MyMissingExtension');
} catch (\Faker\Extension\ExtensionNotFound $e) {
    // not in container
}
```

--------------------------------

### Using optional() with weight and default

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Example usage of optional() to return a fallback value or null based on the weight.

```php
echo $faker->optional(0.9, 'N/A')->name();   // ~90% a name, else 'N/A'
echo $faker->optional(0.1)->email();          // mostly null
```

--------------------------------

### Blood usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Creates a Faker instance and outputs a random blood group, e.g., 'O-'.

```php
$faker = Faker\Factory::create();
echo $faker->bloodGroup();   // 'O-'
```

--------------------------------

### UniqueGenerator usage examples

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/proxy-generators.md

Shows basic unique value generation, handling retry overflow, and resetting the uniqueness scope.

```php
use Faker\Factory;

$faker = Factory::create();

// Basic: unique values across calls
$ids = [];
for ($i = 0; $i < 4; $i++) {
    $ids[] = $faker->unique()->randomDigitNotNull();   // 4 distinct values from 1..9
}

// Non-trivial: explicit retry budget and error handling
try {
    $faker->unique(false, 5)->randomElement(['a', 'b']);   // only 2 values exist
} catch (\OverflowException $e) {
    // "Maximum retries of 5 reached without finding a unique value"
}

// Reset the history
$faker->unique(true)->randomElement(['a', 'b']);   // fresh scope
```

--------------------------------

### numberBetween usage examples

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-number.md

Shows two calls to numberBetween. The second call with reversed bounds behaves identically to the first.

```php
$n = $faker->numberBetween(5, 10);      // 5..10
$n = $faker->numberBetween(10, 5);      // identical behaviour, 5..10
```

--------------------------------

### getFormatters()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Returns an array keyed by provider FQCN, mapping formatter call-signatures to example outputs. This method is useful for auditing custom providers and generating documentation.

```APIDOC
## getFormatters()

### Description
Enumerates all formatters available on the generator, returning a nested array of provider classes and their formatter signatures with example values.

### Method
Public method

### Signature
```php
public function getFormatters()
```

### Returns
- **array** - Keyed by provider FQCN. Each value is an associative array mapping formatter call-signatures (e.g., `'numberBetween($int1 = 0, $int2 = 2147483647)'`) to example outputs.

### Behavior Details
- Reverses `Generator::getProviders()` (oldest first) and appends `Provider\Base`.
- Skips methods declared on `Provider\Base` when the provider is a subtype of it.
- Skips constructors.
- Invokes each public method via `$this->generator->format($methodName)` to capture one example; `InvalidArgumentException` results in an empty string.
- Renders arrays as `array('a', 'b')`, `DateTime` as `DateTime('Y-m-d H:i:s')`, modifier proxies as `''`, and everything else via `var_export`.

### Example
```php
use Faker\Documentor;
use Faker\Factory;

$doc = (new Documentor(Factory::create()))->getFormatters();

foreach ($doc as $providerClass => $formatters) {
    echo $providerClass, "\n";
    foreach ($formatters as $signature => $example) {
        echo "  ", $signature, "  =>  ", $example, "\n";
    }
    break; // only the first provider
}

// Faker\Provider\Address
//   citySuffix()  =>  'town'
//   streetSuffix()  =>  'Street'
//   ...
```

### Notes
- Does not mutate the generator, but consumes random values (advances internal state). This matters only if interleaved with seeded output assertions.
```

--------------------------------

### Using a PSR-11 container with Generator

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Shows how to pass any PSR-11 container (e.g., PHP-DI, Symfony DI) to the Generator, provided it can resolve the eight extension ids. The example retrieves the NumberExtension and calls numberBetween.

```php
use Faker\Generator;

$generator = new Generator($myPsr11Container);
echo $generator->ext(\Faker\Extension\NumberExtension::class)->numberBetween(1, 10);
```

--------------------------------

### Using unique() with reset and maxRetries

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Example usage of unique() to generate non-repeating values, reset the uniqueness scope, and catch OverflowException when exhausted.

```php
$faker->unique()->randomElement(['a', 'b', 'c']);   // never repeats until exhausted
$faker->unique(true)->name();                        // start a fresh uniqueness scope
try {
    $faker->unique(false, 3)->randomElement(['only']);
} catch (\OverflowException $e) { /* exhausted */ }
```

--------------------------------

### getFormatters() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Public method of Documentor that returns an array keyed by provider FQCN, each mapping formatter signatures to example of values, as described in the behavior notes.

```php
public function getFormatters()
```

--------------------------------

### randomNumber usage examples with exception handling

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-number.md

Shows three calls to randomNumber: default, strict, and a try-catch for when digit count exceeds mt_getrandmax().

```php
$n = $faker->randomNumber();          // 0..999999999 (0 to 9 digits)
$n = $faker->randomNumber(4, true);   // exactly 4 digits: 1000..9999

try {
    $faker->randomNumber(12);
} catch (\InvalidArgumentException $e) {
    // digit count exceeds mt_getrandmax()
}
```

--------------------------------

### Loop to Generate Multiple Names

Source: https://github.com/fakerphp/faker/blob/2.0/README.md

Generate and echo three random names using a for loop. The output shows example results, but actual values vary each run.

```php
<?php

declare(strict_types=1);

for ($i = 0; $i < 3; $i++) {
    echo $faker->name() . "\n";
}

// 'Cyrus Boyle'
// 'Alena Cummerata'
// 'Orlo Bergstrom'
```

--------------------------------

### Using withDefaultExtensions and add

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Shows how to create a builder with default extensions, add a custom service, build the container, and retrieve the service.

```php
use Faker\Container\ContainerBuilder;

$builder = ContainerBuilder::withDefaultExtensions();
$builder->add('app.dice', static fn ($c) => new DiceExtension());

$container = $builder->build();
$dice = $container->get('app.dice');   // object
```

--------------------------------

### randomDigitNot usage example

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-number.md

Example call to randomDigitNot, returning a digit from 0 to 9 except 4.

```php
$d = $faker->randomDigitNot(4);   // 0..9 except 4
```

--------------------------------

### Basic usage of Factory::create()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Demonstrates creating a generator with default locale and a specific locale, then generating sample data.

```php
use Faker\Factory;

$faker = Factory::create();                // English (US) data
// or
$faker = Factory::create('de_DE');         // German data

echo $faker->name();        // 'Vince Sporer'
echo $faker->email();       // 'walter.sophia@hotmail.com'
echo $faker->text();        // 'Numquam ut mollitia at consequuntur inventore dolorem.'
```

--------------------------------

### Registering and using Coordinates

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Shows how to manually register Coordinates with a custom builder, then use it. Includes a try-catch for invalid latitude.

```php
$builder = \Faker\Container\ContainerBuilder::withDefaultExtensions();
$builder->add(\Faker\Core\Coordinates::class, new \Faker\Core\Coordinates(new \Faker\Core\Number()));
$faker = new \Faker\Generator($builder->build());
echo $faker->ext(\Faker\Core\Coordinates::class)->latitude();   // e.g. 77.147489

try {
    $faker->ext(\Faker\Core\Coordinates::class)->latitude(-91); // after re-registering
} catch (\LogicException $e) { /* bounds */ }
```

--------------------------------

### Extension-backed convenience methods declarations

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

List of method signatures that forward to core extensions, with line references.

```php
public function mimeType()                       // FileExtension::mimeType()      :755
public function fileExtension()                  // FileExtension::extension()     :765
public function filePath()                       // FileExtension::filePath()      :773
public function bloodType(): string              // BloodExtension::bloodType()    :783
public function bloodRh(): string                // BloodExtension::bloodRh()      :793
public function bloodGroup(): string             // BloodExtension::bloodGroup()   :803
public function ean13(): string                  // BarcodeExtension::ean13()      :813
public function ean8(): string                   // BarcodeExtension::ean8()       :823
public function isbn10(): string                 // BarcodeExtension::isbn10()     :835
public function isbn13(): string                 // BarcodeExtension::isbn13()     :847
public function numberBetween($int1 = 0, $int2 = 2147483647): int   // NumberExtension :857
public function randomDigit(): int               // NumberExtension::randomDigit() :865
public function randomDigitNot($except): int     // NumberExtension::randomDigitNot() :873
public function randomDigitNotZero(): int        // NumberExtension::randomDigitNotZero() :881
public function randomFloat($nbMaxDecimals = null, $min = 0, $max = null): float // :891
public function randomNumber($nbDigits = null, $strict = false): int   // :910
public function semver(bool $preRelease = false, bool $build = false): string // :928
```

--------------------------------

### Class declaration for ValidGenerator

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/proxy-generators.md

Declares the ValidGenerator class. Use this as the starting point for the class definition.

```php
class ValidGenerator
```

--------------------------------

### create() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Signature of the static create() method with docblock.

```php
/**
 * Create a new generator
 *
 * @param string $locale
 *
 * @return Generator
 */
public static function create($locale = self::DEFAULT_LOCALE)
```

--------------------------------

### Using valid() with a validator closure

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Example usage of valid() with a closure to ensure the generated digit is even.

```php
$faker->valid(fn (int $n) => $n % 2 === 0)->randomDigit();  // always even
```

--------------------------------

### Subclassing Factory to override default providers

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Shows how to subclass Factory and override $defaultProviders to swap the provider set, then create a generator with a custom locale.

```php
class MyFactory extends \Faker\Factory
{
    protected static $defaultProviders = ['Address', 'Person', 'Miscellaneous'];
}

$faker = MyFactory::create('fr_FR');
```

--------------------------------

### NotInContainerException class definition

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Defines the NotInContainerException class thrown by get() for unknown ids, implementing Psr\Container\NotFoundExceptionInterface.

```php
final class NotInContainerException extends \RuntimeException implements NotFoundExceptionInterface
```

--------------------------------

### semver(bool $preRelease = false, bool $build = false): string

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Generates a semver 2.0.0 version string. Optionally appends pre-release identifiers like -alpha, -beta, or -rc, and build metadata like a short SHA-1 hash or a date.

```APIDOC
## semver(bool $preRelease = false, bool $build = false): string

### Description
Generates a semver 2.0.0 version string with optional pre-release and build metadata.

### Method
semver

### Signature
`public function semver(bool $preRelease = false, bool $build = false): string`

### Parameters
- **$preRelease** (bool) - Optional - Default: `false` - If true, may append `-alpha[.n]`, `-beta[...]`, or `-rc[...]` (50% chance when enabled).
- **$build** (bool) - Optional - Default: `false` - If true, may append `+<7-hex-sha1-suffix>` or `+<YmdHis date>` (50% chance when enabled).

### Returns
- **string** - A semver 2.0.0 string in the format `major.minor.patch` with major in `[0,9]` and minor/patch in `[0,99]`. Examples: `'1.0.0'`, `'1.0.0-alpha.1'`, `'1.0.0-alpha.1+b71f04d'`.

### Example
```php
$faker = Faker\Factory::create();
echo $faker->semver();            // '2.4.1'
echo $faker->semver(true, true);  // '0.7.99-beta.42+20240801120000'
```
```

--------------------------------

### ContainerBuilder::withDefaultExtensions method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Creates a builder pre-populated with the eight default extension definitions.

```php
public static function withDefaultExtensions(): self
```

--------------------------------

### ext(string $id)

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/proxy-generators.md

Wraps the generator's ext method with the same weight and default logic.

```APIDOC
## ext(string $id)

### Description
Wraps `$this->generator->ext($id)` with the same weight/default.

### Method
`public function ext(string $id)`

### Parameters
- **$id** (string) - Required - The extension identifier.

### Returns
Mixed - The result of the wrapped generator's ext method or the default value.

### Example
```php
$result = $chance->ext('someExtension');
```
```

--------------------------------

### ContainerBuilder::build method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Builds and returns a new Container instance using the accumulated definitions.

```php
public function build(): ContainerInterface
```

--------------------------------

### Faker\Container\ContainerInterface interface

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/types.md

Interface extending Psr\Container\ContainerInterface, inheriting get($id): mixed and has($id): bool. Used for dependency injection containers in Faker.

```php
interface ContainerInterface extends BaseContainerInterface
{
}
```

--------------------------------

### addProvider() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Method signature for addProvider(). It prepends the provider to the stack and invalidates the formatter cache.

```php
public function addProvider($provider)
```

--------------------------------

### build(): ContainerInterface

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Builds and returns a new Container instance using the definitions added to the builder.

```APIDOC
## build(): ContainerInterface

### Description
Builds and returns a new Container instance using the definitions added to the builder.

### Method
build

### Signature
```php
public function build(): ContainerInterface
```

### Returns
- `new Container($this->definitions)`.

```

--------------------------------

### Using Faker\Core\DateTime to generate dates and handle errors

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-datetime.md

Shows how to instantiate Faker\Core\DateTime directly or via the Faker container, then generate a date between two dates, a Unix timestamp, a century, and a date within an interval. Also demonstrates catching an InvalidArgumentException when the 'from' date is after the 'until' date.

```php
use Faker\Core\DateTime;

$dt = new DateTime();                          // generator-aware; call via container:
$faker = Faker\Factory::create();
$date = $faker->ext(\Faker\Extension\DateTimeExtension::class);

// Basic
echo $date->dateTimeBetween('-1 week', 'now')->format('Y-m-d H:i');
echo $date->unixTime();                        // e.g. 1061306726
echo $date->century();                         // 'XVII'

// Non-trivial: interval + error handling
$in = $date->dateTimeInInterval('1999-02-02 11:42:52', '+5 days');
try {
    $date->dateTimeBetween('now', '-30 years');
} catch (\InvalidArgumentException $e) {
    // '"$from" must be anterior to "$until".'
}
```

--------------------------------

### Faker\Core\File::filePath()

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Creates a real temporary file using `tempnam()` and returns its path.

```APIDOC
## `filePath()`

### Description
Creates a new temporary file on disk and returns its path.

### Method
`filePath`

### Signature
`public function filePath(): string`

### Returns
- **string** - A real, newly-created temporary file path, e.g. `'/tmp/fakerAb12Cd34'`.

### Example
```php
$faker = Faker\Factory::create();
echo $faker->filePath(); // '/tmp/fakerAb12Cd34' (creates the file on disk)
```
```

--------------------------------

### ext() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Method signature for ext() with docblock. It resolves an extension by its class-string id and returns the extension instance, throwing ExtensionNotFound if not registered.

```php
/**
 * @template T of Extension\Extension
 *
 * @param class-string<T> $id
 *
 * @throws Extension\ExtensionNotFound
 *
 * @return T
 */
public function ext(string $id): Extension\Extension
```

--------------------------------

### Extension-backed convenience methods

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Convenience methods that forward to named extensions, providing common data generation.

```APIDOC
## Extension-backed convenience methods

### Description
These methods have real implementations on `Generator` (not magic dispatch) and forward to the named extension.

### Methods
- `mimeType()` - FileExtension::mimeType()
- `fileExtension()` - FileExtension::extension()
- `filePath()` - FileExtension::filePath()
- `bloodType(): string` - BloodExtension::bloodType()
- `bloodRh(): string` - BloodExtension::bloodRh()
- `bloodGroup(): string` - BloodExtension::bloodGroup()
- `ean13(): string` - BarcodeExtension::ean13()
- `ean8(): string` - BarcodeExtension::ean8()
- `isbn10(): string` - BarcodeExtension::isbn10()
- `isbn13(): string` - BarcodeExtension::isbn13()
- `numberBetween($int1 = 0, $int2 = 2147483647): int` - NumberExtension
- `randomDigit(): int` - NumberExtension::randomDigit()
- `randomDigitNot($except): int` - NumberExtension::randomDigitNot()
- `randomDigitNotZero(): int` - NumberExtension::randomDigitNotZero()
- `randomFloat($nbMaxDecimals = null, $min = 0, $max = null): float` - NumberExtension
- `randomNumber($nbDigits = null, $strict = false): int` - NumberExtension
- `semver(bool $preRelease = false, bool $build = false): string` - NumberExtension

### Parameters
All accept the documented parameters (not repeated here; see core-misc.md, core-number.md), coerce inputs (`(int)`, `(float)`, `(bool)`), and throw whatever the underlying extension throws — e.g. `randomNumber()` throws `\InvalidArgumentException` when the requested digit count exceeds `mt_getrandmax()`.

### Example
```php
echo $faker->numberBetween(1, 6);   // 1..6
echo $faker->semver(true, true);    // e.g. 2.4.1-beta.3+abc1234
echo $faker->bloodGroup();          // e.g. 'AB+'
echo $faker->ean13();               // e.g. '4006381333931'
```
```

--------------------------------

### Faker\Extension\Helper

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/extension-system.md

Static utility class providing helper methods for building extensions. Marked as `@experimental`.

```APIDOC
## `Faker\Extension\Helper`

### Description
Static utility class providing helper methods for building extensions. Marked as `@experimental`.

### Methods

#### `randomElement(array $array): mixed|null`
- **Parameters**: `$array` (array) - Required - Input array.
- **Returns**: mixed|null - A random element, or `null` for empty array.
- **Notes**: Uses `array_rand($array, 1)`.

#### `randomNumber(): int`
- **Parameters**: None
- **Returns**: int - A random integer.
- **Notes**: Uses `mt_rand()`.

#### `randomNumberBetween(int $min, int $max): int`
- **Parameters**: `$min` (int) - Required - Minimum value. `$max` (int) - Required - Maximum value.
- **Returns**: int - A random integer between min and max.
- **Notes**: Uses `mt_rand($min, $max)`.

#### `largestRandomNumber(): int`
- **Parameters**: None
- **Returns**: int - The largest possible random number.
- **Notes**: Uses `mt_getrandmax()`.

#### `numerify(string $string): string`
- **Parameters**: `$string` (string) - Required - Input string.
- **Returns**: string - String with `#` replaced by 0-9 and `%` replaced by 1-9.
- **Notes**: Uses batched random generation and `replaceWildcard` helper.

#### `lexify(string $string): string`
- **Parameters**: `$string` (string) - Required - Input string.
- **Returns**: string - String with `?` replaced by lowercase ASCII letters (a-z).
- **Notes**: Uses `chr(97..122)`.

#### `bothify(string $string): string`
- **Parameters**: `$string` (string) - Required - Input string.
- **Returns**: string - String with `*` first becoming `#` or `?`, then numerify and lexify applied.
- **Notes**: Mixed wildcard replacement.
```

--------------------------------

### Set and get default timezone

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/configuration.md

Use setDefaultTimezone to configure the timezone used by date formatters when no timezone argument is given. getDefaultTimezone returns the configured timezone or null.

```php
Faker\Provider\DateTime::setDefaultTimezone('Europe/Paris'); // src/Provider/DateTime.php:365
$tz = Faker\Provider\DateTime::getDefaultTimezone();         // 'Europe/Paris' or null
```

--------------------------------

### Run Rector with Faker Migration Config

Source: https://github.com/fakerphp/faker/blob/2.0/README.md

Run Rector using the provided migration config to refactor your code. Replace 'src/' with your source directory path.

```bash
vendor/bin/rector process src/ --config vendor/fakerphp/faker/rector-migrate.php
```

--------------------------------

### dateTimeThisCentury($until = 'now', string $timezone = null): \DateTime

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-datetime.md

Generates a random DateTime within the current century, from the first day of January of the century's start year to the specified end date.

```APIDOC
## dateTimeThisCentury($until = 'now', string $timezone = null): \DateTime

### Description
Generates a random DateTime within the current century, starting from the first day of January of the century's start year.

### Method
DateTime generation

### Endpoint
Faker\Core\DateTime::dateTimeThisCentury

### Parameters
#### Parameters
- **$until** (string) - Optional - Default: 'now' - Upper bound for the century
- **$timezone** (string|null) - Optional - Default: null - Output timezone

### Returns
- **\DateTime** - A random DateTime between "first day of january $year" and $until, where $year = floor(date('Y')/100)*100.
```

--------------------------------

### Container constructor with docblock

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Constructor for the Container class. Accepts an array of definitions where each value must produce an object implementing Faker\Extension\Extension.

```php
/**
 * Create a container object with a set of definitions. The array value MUST
 * produce an object that implements Extension.
 *
 * @param array<string, callable|object|string> $definitions
 */
public function __construct(array $definitions)   // src/Container/Container.php:32
```

--------------------------------

### dateTimeThisDecade($until = 'now', string $timezone = null): \DateTime

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-datetime.md

Generates a random DateTime within the current decade, from the first day of January of the decade's start year to the specified end date.

```APIDOC
## dateTimeThisDecade($until = 'now', string $timezone = null): \DateTime

### Description
Generates a random DateTime within the current decade, starting from the first day of January of the decade's start year.

### Method
DateTime generation

### Endpoint
Faker\Core\DateTime::dateTimeThisDecade

### Parameters
#### Parameters
- **$until** (string) - Optional - Default: 'now' - Upper bound for the decade
- **$timezone** (string|null) - Optional - Default: null - Output timezone

### Returns
- **\DateTime** - A random DateTime between "first day of january $year" and $until, where $year = floor(date('Y')/10)*10.
```

--------------------------------

### new Documentor(Generator $generator)

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Constructs a new Documentor instance with a Generator whose providers will be documented.

```APIDOC
## Constructor

### Description
Creates a new Documentor instance that will enumerate formatters from the given generator.

### Method
Constructor

### Signature
```php
public function __construct(Generator $generator)
```

### Parameters
- **$generator** (`Faker\Generator`) - Required - The generator whose providers are to be documented.

### Example
```php
$doc = new Documentor(Factory::create());
```
```

--------------------------------

### VersionExtension interface

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/extension-system.md

Defines a method for generating semantic version strings, with optional pre-release and build metadata.

```php
interface VersionExtension extends Extension
{
    public function semver(bool $preRelease = false, bool $build = false): string;
}
```

--------------------------------

### Generator-aware extension with GreetingExtension

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/extension-system.md

Defines GreetingExtension implementing GeneratorAwareExtension and using GeneratorAwareExtensionTrait. The hello() method accesses $this->generator->firstName(), which is bound by Generator::ext(). This allows the extension to use arbitrary formatters from the generator.

```php
use Faker\Extension\Extension;
use Faker\Extension\GeneratorAwareExtension;
use Faker\Extension\GeneratorAwareExtensionTrait;
use Faker\Generator;

final class GreetingExtension implements GeneratorAwareExtension
{
    use GeneratorAwareExtensionTrait;

    public function hello(): string
    {
        return 'Hello ' . $this->generator->firstName();   // $generator bound by Generator::ext()
    }
}
```

--------------------------------

### Constructor signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/factory.md

Constructor for Documentor that accepts a Generator instance whose providers will be documented.

```php
public function __construct(Generator $generator)   // src/Documentor.php:9
```

--------------------------------

### Helper class with static utilities

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/extension-system.md

Final class with static utility methods for building extensions. Marked @experimental. Methods include randomElement, randomNumber, randomNumberBetween, largestRandomNumber, numerify, lexify, and bothify.

```php
final class Helper
{
    public static function randomElement(array $array);        // :15  — null for empty array
    public static function randomNumber(): int;                // :24  — mt_rand()
    public static function randomNumberBetween(int $min, int $max): int;  // :29
    public static function largestRandomNumber(): int;         // :34  — mt_getrandmax()
    public static function numerify(string $string): string;   // :45  — '#' → digit, '%' → 1..9
    public static function lexify(string $string): string;     // :85  — '?' → a-z
    public static function bothify(string $string): string;    // :98  — '#'/'?'/'*' mixed
}
```

--------------------------------

### Constructor

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Creates a new Generator instance with an optional service container for resolving extensions.

```APIDOC
## Constructor

### Description
Creates a new Generator instance. The optional container is used by the `ext()` method to resolve extension services.

### Method
`__construct`

### Signature
```php
public function __construct(ContainerInterface $container = null)
```

### Parameters
- `$container` (`Faker\Container\ContainerInterface`, PSR-11) - Optional - Default: `ContainerBuilder::withDefaultExtensions()->build()` - Service container resolving extension ids used by `ext()`.

```

--------------------------------

### withDefaultExtensions(): self

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Creates a builder pre-populated with the eight default extension definitions. This is exactly what Generator::__construct() uses when no container is passed.

```APIDOC
## withDefaultExtensions(): self

### Description
Creates a builder pre-populated with the eight default extension definitions. This is exactly what Generator::__construct() uses when no container is passed.

### Method
withDefaultExtensions

### Signature
```php
public static function withDefaultExtensions(): self
```

### Returns
- A new builder instance with default extensions.

### Example
```php
use Faker\Container\ContainerBuilder;

$builder = ContainerBuilder::withDefaultExtensions();
$builder->add('app.dice', static fn ($c) => new DiceExtension());

$container = $builder->build();
$dice = $container->get('app.dice');   // object
```

```

--------------------------------

### Constructor with NumberExtension dependency

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-color.md

Constructor that requires a NumberExtension instance to provide random numbers for all color generation methods.

```php
public function __construct(Extension\NumberExtension $numberExtension)   // src/Core/Color.php:57
```

--------------------------------

### Basic custom extension with DiceExtension

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/extension-system.md

Defines a DiceExtension implementing Extension, registers it in a custom container, and demonstrates usage via ext(), format string, and parse token. Requires Faker\Container\ContainerBuilder, Faker\Extension\Extension, Faker\Factory, and Faker\Generator. The roll() method uses Helper::randomNumberBetween to respect the generator's seed. Note: the default container only maps eight extension ids; requesting others throws ExtensionNotFound.

```php
use Faker\Container\ContainerBuilder;
use Faker\Extension\Extension;
use Faker\Factory;
use Faker\Generator;

final class DiceExtension implements Extension
{
    public function roll(int $sides = 6): int
    {
        return \Faker\Extension\Helper::randomNumberBetween(1, $sides);
    }
}

$builder = ContainerBuilder::withDefaultExtensions();
$builder->add(DiceExtension::class, new DiceExtension());

$faker = new Generator($builder->build());          // custom container
echo $faker->ext(DiceExtension::class)->roll(20);    // 1..20
echo $faker->format('DiceExtension->roll');          // identical via string selector
echo $faker->parse('{{ DiceExtension->roll }}');     // works inside parse() tokens
```

--------------------------------

### parse($string)

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Replaces every `{{ token }}` in a string with the matching formatter output. This is how providers compose outputs.

```APIDOC
## `parse($string)`

### Description
Replaces every `{{ token }}` in a string with the matching formatter output. This is how providers compose outputs.

### Method
`parse`

### Signature
`public function parse($string)`

### Parameters
- `$string` (string) - Required - Template containing `{{ tokenName }}` (or `{{ Faker\Core\Barcode->ean13 }}` for extensions) tokens.

### Return Value
Returns the string with every `{{ token }}` replaced by the matching formatter output.

### Example
```php
echo $faker->parse('{{titleMale}} {{firstNameMale}} {{lastName}} @ {{freeEmailDomain}}');
```
```

--------------------------------

### semver() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Defines the semver() method with optional $preRelease and $build parameters. When $preRelease is true, it may append -alpha[.n], -beta[...], or -rc[...] with a 50% chance. When $build is true, it may append +<7-hex-sha1-suffix> or +<YmdHis date> with a 50% chance. Returns a semver 2.0.0 string like '1.0.0', '1.0.0-alpha.1', or '1.0.0-alpha.1+b71f04d'.

```php
public function semver(bool $preRelease = false, bool $build = false): string   // src/Core/Version.php:30
```

--------------------------------

### rgbColor(): string

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-color.md

Returns a comma-separated string of RGB channel values.

```APIDOC
## rgbColor(): string

### Description
Returns a comma-separated string of RGB channel values.

### Method
rgbColor

### Returns
- **string** - A string like '0,255,122'.

### Example
```php
$color->rgbColor(); // '0,255,122'
```
```

--------------------------------

### Container::get() method with docblock

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Resolves a service by its id. Returns the service object, cached after first resolution. Throws various exceptions for invalid ids, unknown ids, or resolution failures.

```php
/**
 * @param string $id
 *
 * @throws \InvalidArgumentException
 * @throws \RuntimeException
 * @throws ContainerException
 * @throws NotInContainerException
 */
public function get($id): object
```

--------------------------------

### getProviders() method signature

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Method signature for getProviders(). Returns an array of provider objects in resolution order.

```php
public function getProviders()
```

--------------------------------

### Import Rector Config in rector.php

Source: https://github.com/fakerphp/faker/blob/2.0/README.md

Import the Faker migration config into your project's rector.php file to enable automated refactoring.

```php
<?php

declare(strict_types=1);

use Rector\Config;

return static function (Config\RectorConfig $rectorConfig): void {
    $rectorConfig->import('vendor/fakerphp/faker/rector-migrate.php');
};
```

--------------------------------

### seed($seed = null)

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Seeds PHP's Mersenne Twister to make subsequent output reproducible for a fixed seed.

```APIDOC
## `seed($seed = null)`

### Description
Seeds PHP's Mersenne Twister, making subsequent output reproducible for a fixed seed.

### Method
`seed`

### Signature
`public function seed($seed = null)`

### Parameters
- `$seed` (int|null) - Optional - Default: `null` - If `null`, calls `mt_srand()` (random); else `mt_srand((int) $seed, MT_RAND_PHP)`.

### Return Value
No return value.

### Example
```php
$faker = Faker\Factory::create();
$faker->seed(1234);
$a = $faker->name();
$faker->seed(1234);
$b = $faker->name();   // $a === $b
```
```

--------------------------------

### Faker\Container\Container::__construct

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/container.md

Constructor for the Container class, accepting a definitions array.

```APIDOC
## Container::__construct

### Description
Creates a container with a set of definitions. Definitions must produce objects implementing Faker\Extension\Extension.

### Method
__construct

### Parameters
- `$definitions` (array<string, callable|object|string>) - Required - id → definition map

### Throws
- No exceptions documented for constructor.

```

--------------------------------

### format($format, $arguments = [])

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/generator.md

Calls a formatter by name, optionally with positional arguments. Returns the formatter result.

```APIDOC
## `format($format, $arguments = [])`

### Description
Calls a formatter by name, optionally with positional arguments. Returns the formatter result.

### Method
`format`

### Signature
`public function format($format, $arguments = [])`

### Parameters
- `$format` (string) - Required - Formatter name (or `"Class->method"` extension selector).
- `$arguments` (array) - Optional - Default: `[]` - Positional arguments forwarded with `call_user_func_array`.

### Return Value
Returns the formatter result (any type). Throws `\InvalidArgumentException` for unknown formats.

### Example
```php
$faker->format('name');                  // same as $faker->name()
$faker->format('numberBetween', [1, 10]);
$faker->format('Faker\Core\Barcode->ean13');  // extension-direct call
```
```

--------------------------------

### Barcode constructor

Source: https://github.com/fakerphp/faker/blob/2.0/_autodocs/api-reference/core-misc.md

Constructor for the Barcode extension, requiring a NumberExtension instance.

```php
public function __construct(Extension\NumberExtension $numberExtension)
```
Tokens:
Raw