New FakerPHP support

[martinsoenen]

Context

Following recent discussions with @nikophil , I'd like to open this issue to gather feedback on integrating xefi/faker-php into Foundry as an optional alternative to fakerphp/faker.

We agreed that we should probably let users choose between the two implementations. This would probably be in Foundry 3, switchable via configuration.

@GautierDele and I maintain xefi/faker-php and are happy to do the integration work. This issue is mostly about aligning on the approach (and on the two open questions below) before we start.

About xefi/faker-php

xefi/faker-php is an actively maintained, modular reimplementation of Faker for PHP 8.3+ (MIT).

$faker = new Xefi\Faker\Faker();
$faker->name();   // John Doe
$faker->iban();   // PX41711762752955497163783543

Unlike fakerphp/faker, it ships a small core and moves providers and locales into dedicated, opt-in extension packages (e.g. xefi/faker-php-images, xefi/faker-php-files, xefi/faker-php-currencies, and per-locale packages such as xefi/faker-php-locales-en-us).

Proposed action items

Pending validation from the Foundry team, we're happy to own the following:

1. Deprecation layer : a dedicated bridge package mapping legacy methods to their new counterparts. Both implementations could then run in parallel, keeping breaking changes to a minimum while guiding users toward the new API through deprecation notices.
2. Dual-Faker support in Foundry : support both fakerphp/faker and xefi/faker-php on the Foundry side, selectable through a configuration option, so teams can migrate at their own pace.
3. Locale coverage : xefi/faker-php currently covers fewer locales than fakerphp/faker (locales are opt-in packages). If locale coverage turns out to be a blocker, could you let us know which specific locales are critical for Foundry users, so we can prioritize implementing them?
4. Seeding compatibility : verify that Foundry's seeding mechanism integrates cleanly with xefi/faker-php's seeding system, so reproducible data generation and seed-based workflows keep working after a migration.
5. Rector rules : Maybe we can create a rule set to automate migration from the old Faker method calls to the new ones, so end users can migrate with minimal manual work. But if we ensure point 4, it should be useless to create Rector rules.

Open questions

Two design points I'd like the team's input :

1. Single entry point vs. explicit autocompletion

In a factory, the current entry point is self::faker(), which returns a Faker\Generator. With xefi/faker-php it would return a Xefi\Faker\Faker instance instead. I'd really like to keep a single entry point, but I can't see how to make autocompletion explicit about which implementation is returned without introducing a second method (e.g. self::theNewFaker()). Has anyone got a cleaner idea here?

2. Dependency management during the v2 → v3 transition

In Foundry 3, we expect the hard dependency on fakerphp/faker in composer.json to be dropped. That means the last Foundry 2 releases will need a way to make users explicitly require-dev one of the two libraries. What's the cleanest approach for you ? A Composer conflict/replace trick, a runtime check with a helpful error pointing users to install one of the two libs, docs-only guidance, or something else?

Keen to hear the team's thoughts on the overall direction and on the two open questions above. Once we've agreed on an approach, we're ready to start with a prototype / draft PR.

[nikophil]

Hi @martinsoenen

1. Deprecation layer : a dedicated bridge package mapping legacy methods to their new counterparts. Both implementations could then run in parallel, keeping breaking changes to a minimum while guiding users toward the new API through deprecation notices.

I really think this stuff would ease migration, and not only for Foundry! Have you already listed all the differences between both old and new apis?

2. Dual-Faker support in Foundry : support both fakerphp/faker and xefi/faker-php on the Foundry side, selectable through a configuration option, so teams can migrate at their own pace.

My guess for this would be:

• if Faker's version is forced within the conf, let's use this one
• otherwise, let's check if one and only one faker package exists. If it's the case, let's automatically use it
• if none exists => throw (only in 3.x, this won't be the case in 2.x)
• if both exist (and none is configured) => throw (this should be done from day 1, in Foundry 2.x)

About the config: we should provide two kinds: Foundry can actually be used without any framework, so:

• "no framework" (ie: using PHPUnit\Framework\TestCase) => the configuration will land in Zenstruck\Foundry\Test\UnitTestConfig
• "with framework" (ie: using Symfony\Bundle\FrameworkBundle\Test\KernelTestCase) => configuration will be read from bundle's config

3. Locale coverage : xefi/faker-php currently covers fewer locales than fakerphp/faker (locales are opt-in packages). If locale coverage turns out to be a blocker, could you let us know which specific locales are critical for Foundry users, so we can prioritize implementing them?

We currently have no clue about this, that's totally depending on the final users. I personally am perfectly fine with en_US and fr_FR. If some people ask here to add new locale, we will redirect them to your repo and ask them to open an issue there.

4. Seeding compatibility : verify that Foundry's seeding mechanism integrates cleanly with xefi/faker-php's seeding system, so reproducible data generation and seed-based workflows keep working after a migration.

After checking new faker's code, I think this will be problematic: I don't see any place where it's possible to fix a seed in xefi/faker-php 🤔 I would have expected that all extensions share the same Random\Engine, but it appears that it is not the case: given this line the randomizer is created with a null engine, which basically uses a Random\Engine\Secure under the hood, which prevents reproducible builds.

In order to have reproducible builds, we'd need a way to provide a seed to the randomizer, and to reset the randomizer.
Basically, with old faker, this is done using method Faker\Generator::seed(), which calls mt_srand($seed).

With the new PHP's randomizer API, It could be done this way: new \Random\Randomizer(new \Random\Engine\Mt19937($seed)).
And in order to reset the seed between each test, a new randomizer should be recreated.

So unless I'm missing something, I think few things are missing in the new faker's implementation around this: basically a way to chose a seed and propagate it to all extensions and existing randomizers. Any thoughts about that? I can open an issue in your repo to talk about this.

I asked Claude about this point, here is the answer:

The question

We're in the repo of a library that aims to replace fakerphp/faker.
But I get the feeling we can't have reproducible builds: there's no way to pass a seed. What do you think?

Verdict

You're right — as it stands, builds are not reproducible. It's not a config detail, it's structural.

---

The diagnosis

All generation relies on Random\Randomizer, and it's instantiated everywhere with no engine:

Location	Code
HasExtensions.php:52	new $extension(new Randomizer())
HasModifiers.php:30	new NullableModifier(new Randomizer(), $weight)

A new Randomizer() with no argument defaults to the Random\Engine\Secure engine (the OS CSPRNG). That engine is deliberately non-seedable — it's built for crypto, precisely so
the sequence cannot be replayed. So today there's no entry point to fix a seed.

---

The trap: HasSeeds / forSeed() is not an RNG seed

Don't be fooled by the naming:

• Seeds\HasSeeds trait
• UniqueStrategy::forSeed() (HasStrategies.php:28)

These have nothing to do with reproducibility. It's just an instance cache memoized by a string key, so the unique strategy remembers already-drawn values between calls. It doesn't
influence the random flow at all. The word "seed" here is misleading.

---

What I think of the fix

Good news: the lib already uses Random\Randomizer (modern PHP 8.2+ API), so the fix is cleaner than in fakerphp/faker. Legacy Faker does a global mt_srand() — global state,
ugly, leaks between tests. Here you just inject a seedable engine:

$engine     = new \Random\Engine\Xoshiro256StarStar($seed); // or Mt19937($seed)
$randomizer = new \Random\Randomizer($engine);

A seeded engine replays the exact same sequence. That's the canonical, state-free approach.

But — two real architectural obstacles

1. Extensions are cached statically (static array $extensions) and each gets its own Randomizer at construction, once for the whole process. So ->name() and ->sentence() draw from two
   independent engines.
   → For a reproducible run you need either a single shared engine injected into all extensions/modifiers, or per-extension engines deterministically derived from a master seed.
2. Seeding after the fact. Extensions are already instantiated and cached by the time you'd call seed(). Random\Engine engines can't be re-seeded in place — you have to build a new one and
   push it back into the extensions.
   → Either add a setRandomizer() on Extension, or make the Container hold the Randomizer and pass it at callExtensionMethod() time rather than at construction.

---

Recommendation

This is a blocking gap for a library aiming to replace fakerphp/faker — reproducible fixtures/tests are a major use case (note the "seeding" keyword in their own composer.json). Treat it as
a real feature, not a quick fix.

Target user-facing API, aligned with what people already know:

$faker = new \Xefi\Faker\Faker();
$faker->seed(1234); // everything after this is deterministic

5. Rector rules : Maybe we can create a rule set to automate migration from the old Faker method calls to the new ones, so end users can migrate with minimal manual work. But if we ensure point 4, it should be useless to create Rector rules.

yes, I think Rector rules would be useless, moreover if a deprecation layer package is provided 👍

In a factory, the current entry point is self::faker(), which returns a Faker\Generator. With xefi/faker-php it would return a Xefi\Faker\Faker instance instead. I'd really like to keep a single entry point, but I can't see how to make autocompletion explicit about which implementation is returned without introducing a second method (e.g. self::theNewFaker()). Has anyone got a cleaner idea here?

I still have no idea how to resolve this problem, this is my main blocker (+ the seed stuff). Maybe a facade with some @mixin tags? Don't know, how it would behave both in PHPStan or PHPStorm, we should experiment here.

In Foundry 3, we expect the hard dependency on fakerphp/faker in composer.json to be dropped. That means the last Foundry 2 releases will need a way to make users explicitly require-dev one of the two libraries. What's the cleanest approach for you ? A Composer conflict/replace trick, a runtime check with a helpful error pointing users to install one of the two libs, docs-only guidance, or something else?

The ideal would be to check if Foundry is the only vendor requiring faker (an equivalent to composer why fakerphp/faker but programmatically - and cached).
The workflow should be something like this:

• detect which faker's version will be needed
• if Xefi's => do nothing
• if old faker => detect if the main app requires it from another source than Foundry
• if not => emit a deprec

---

I'd really like that we find a solution for the seed and the typing problems. When we'll be OK on those, let's write a checklist in this issue for everything we need to achieve this migration.

cheers!

[smnandre]

and per-locale packages such as xefi/faker-php-locales-en-us

Thank you for that 👍