Faker Php Laravel Package

Getting Started

Know what you're installing. xefi/faker-php is the framework-agnostic core engine only. There is no Laravel service provider, no facade, and no locale data in this repository — those live in xefi/faker-php-laravel and xefi/faker-php-locales-*. If you composer require this package alone into a Laravel app you get a working generator, but you write your own wiring. For day-to-day Laravel work, install the bridge and at least one locale package alongside it.

composer require --dev xefi/faker-php
composer require --dev xefi/faker-php-laravel          # Laravel integration
composer require --dev xefi/faker-php-locales-<your>  # locale data

Use --dev unless your seeders run inside a deploy pipeline that installs with --no-dev.

Check your PHP floor first. This requires PHP 8.3+. Laravel 10/11 apps on 8.1/8.2 cannot use it at all, and it is not worth bumping your runtime just for seed data. Confirm with composer why-not php 8.3 before you plan anything around it.

Look at two generated files before you look at docs. vendor/xefi/faker-php/packages.php lists every provider the manifest discovered, and faker_mixin.php is a @method docblock stub giving IDE autocompletion for whatever extensions are actually installed. That stub is the fastest, most accurate API index you will get — far better than reading extension source. Both are git-ignored build artifacts, and both recompile automatically when vendor/composer/installed.json or your project composer.json is newer than the file.

First use case. Seed one model with a strategy and a unique field, not a whole fixture suite:

User::factory()->create([
    'email' => $faker->unique()->email(),
    'handle' => $faker->strategy(fn ($v) => strlen($v) > 6)->userName(),
]);

If that runs twice in the same process without exploding, you understand the two things that bite people most (see Gotchas).

Implementation Patterns

Keep it out of the fake() hot path at first. Laravel already ships fakerphp/faker behind fake() and Faker\Generator in factories. Replacing that wholesale is a migration, not an adoption. The pragmatic path is coexistence: use xefi explicitly in new seeders and in test setup where you want the strategy/modifier pipeline, and leave existing factories on fake() until they need touching. Mixing the two in one factory is where confusion starts — pick one per file.

Standalone / console / non-Laravel contexts. The entry point is Xefi\Faker\Faker; every call constructs a fresh Container, so modifiers and strategies never leak between calls. That is a genuinely nice property and it means you can freely build one instance per test method without worrying about polluted state:

$faker = new \Xefi\Faker\Faker();
$faker->email();

Register your own generators as an app-level provider. The PackageManifest reads extra.faker.providers from every installed package and from your project's own composer.json. So you do not need to publish a package to add domain generators — add a DomainExtension class with public methods and wire it in your app's extra.faker.providers. Every public method becomes a Faker method automatically (getName() and __construct are skipped). This is the single most valuable extension point for a Laravel team: invoiceNumber(), sku(), tenantSlug() live next to your models instead of being copy-pasted into seeders.

Prefer strategies over hand-rolled loops. run() generates a value, applies modifiers, then retries until strategies pass — capped at 20 000 attempts. For constraint-heavy data (a date in a range, an amount that satisfies a business rule), a strategy beats a while loop in a seeder because it fails loudly with MaximumTriesReached instead of hanging your test suite.

Seeded determinism is the reason to choose this over fakerphp. Randomness routes through an injected Random\Randomizer, so a seeded engine gives reproducible output. That makes it viable for snapshot-style tests and for reproducing a flaky CI failure locally. Seed it per-test, not globally, so one test's seed cannot mask another's flakiness.

Locale switching is a container concern, not a data concern. Locale-aware extensions resolve the variant matching the current locale and fall back to the default. Add locales by installing packages; never by editing vendor files or adding arrays to the core.

CI note: composer install regenerates the IDE mixin via post-install-cmd, and the test suite runs PHPUnit 12. If your pipeline caches vendor/ aggressively, stale manifests are a real failure mode — see below.

Gotchas and Tips

Never call unique() on a bounded set. The unique pool is process-global, seed-keyed, and never reset. Over an enum, a fixed list, or a small integer range it exhausts and then throws MaximumTriesReached on every subsequent call in that process — including calls in unrelated tests. Widen the range or iterate the set deterministically instead. This is the number one way this package will ruin an afternoon.

Extension and bootstrapper registries are static and process-global. They survive between tests. Bootstrappers also accumulate: every provider boot appends a Container::starting() callback. To re-initialise extensions through the constructor in a test, call both forgetExtensions() and forgetBootstrappers() — forgetting only the first means providers register twice and every extension fires an "already registered" warning that looks like a package bug but is your test setup.

Method names are globally unique across all extensions. A collision triggers E_USER_WARNING and the last registration silently overwrites the method; for locale variants the already-mapped method is kept silently. If a generator starts returning something plausible-but-wrong after you added a package, suspect a name clash before you suspect the data. Name your domain extensions with a prefix.

Seeded reproducibility has known holes. uuid(), ulid(), phoneNumber() and url() bypass the injected randomizer — documented as debt, not as design. Do not build a "byte-identical output" test on top of those methods.

Manifests recompile on mtime comparison, which is not always reliable. After adding or removing a provider package, if methods are missing or an old generator still resolves, delete packages.php and faker_mixin.php and re-run composer generate-mixin (or composer install). Never commit either file; they are git-ignored for good reason and merge conflicts in them are pure noise.

Do not expect declare(strict_types=1) in this codebase's src/. Irrelevant to consumers, but it explains surprising loose typing at the boundaries — validate what comes back from mixed-ish methods before trusting it in a typed property.

Maturity check for a team decision. ~188 stars, zero dependents, and a young release history. It is Apache-2.0 and small enough to audit, and being framework-agnostic means an exit costs little — but it is not a drop-in replacement for a package every Laravel app already has. Prototype in tests and seeders for a sprint before proposing it as a project standard, and keep factory() definitions portable so backing out is a diff, not a rewrite.