Getting Started

Install as a dev dependency, since this is a seeding/testing tool:

composer require nonsapiens/realaddressfactory --dev

Laravel 11+ should auto-discover the service provider. If you are on a non-standard skeleton, register it in bootstrap/providers.php. If the package ships a config file, publish it only when you need to override dataset paths or default locales:

php artisan vendor:publish --tag=realaddressfactory-config

Look first at:

The package README’s usage section — the public surface is small: a factory/entry class and, usually, a Faker provider.
config/realaddressfactory.php, if present, for supported locales and dataset settings.
The installed source under vendor/nonsapiens/realaddressfactory/src to confirm exact method names and return shape for your version.

A first useful use case is replacing fake, obviously bogus addresses in a seeder with plausible real-world ones:

use Nonsapiens\RealAddressFactory\RealAddressFactory;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        $address = RealAddressFactory::make('nl');

        \App\Models\Address::create([
            'street'        => $address['street'],
            'house_number'  => $address['house_number'],
            'postcode'      => $address['postcode'],
            'city'          => $address['city'],
            'country'       => $address['country'],
        ]);
    }
}

If your installed version exposes the Faker integration, the equivalent is often:

$address = fake()->realAddress();

Implementation Patterns

Use it inside model factories

Keep address generation close to the model that owns the address:

class AddressFactory extends Factory
{
    public function definition(): array
    {
        $address = RealAddressFactory::make('nl');

        return [
            'street'       => $address['street'],
            'house_number' => $address['house_number'],
            'postcode'     => $address['postcode'],
            'city'         => $address['city'],
            'country'      => $address['country'],
        ];
    }
}

Then seed normally:

Address::factory()->count(50)->create();

Register the Faker provider once

If you prefer fake()->realAddress() everywhere, add the provider in a service provider rather than in every test or seeder:

use Faker\Generator as FakerGenerator;
use Nonsapiens\RealAddressFactory\Faker\RealAddressProvider;

public function register(): void
{
    $this->app->afterResolving(FakerGenerator::class, function (FakerGenerator $faker) {
        $faker->addProvider(new RealAddressProvider($faker));
    });
}

Then factories, tests, and seeders share the same provider.

Choose locale deliberately

Real address datasets are locale-specific. Match the package locale to the audience of the data you are seeding:

$nl = RealAddressFactory::make('nl');
$be = RealAddressFactory::make('be');
$de = RealAddressFactory::make('de');

If the package relies on Faker’s locale, set it explicitly in the test or seeder:

config(['app.faker_locale' => 'nl_NL']);

or use a dedicated Faker instance:

$faker = \Faker\Factory::create('nl_NL');

Bulk generation

For larger seeds, generate in a loop and insert in batches rather than calling the factory for every row:

$rows = [];

for ($i = 0; $i < 500; $i++) {
    $a = RealAddressFactory::make('nl');

    $rows[] = [
        'street'       => $a['street'],
        'house_number' => $a['house_number'],
        'postcode'     => $a['postcode'],
        'city'         => $a['city'],
        'country'      => $a['country'],
    ];
}

Address::insert($rows);

This avoids repeated container resolution and keeps memory predictable.

Testing patterns

Use real addresses to test address formatting, geocoding boundaries, shipping-zone logic, or checkout flows — not to assert exact street names. Assert structure and invariants instead:

$address = RealAddressFactory::make('nl');

expect($address)
    ->toHaveKeys(['street', 'house_number', 'postcode', 'city', 'country'])
    ->and($address['postcode'])->toMatch('/^\d{4}\s?[A-Z]{2}$/');

If the package exposes a seeding method for determinism, use it in tests that need repeatable output. Otherwise, treat the values as real-world fixtures: realistic but not stable across runs.

Combine with geospatial fields

A common pattern is to use the package for postal address fields and a separate deterministic or mocked source for latitude/longitude:

$address = RealAddressFactory::make('nl');

Location::create([
    ...$address,
    'latitude'  => 52.3702,
    'longitude' => 4.8952,
]);

Do not assume the package returns coordinates unless the README explicitly says so.

Gotchas and Tips

Method names vary by version. The package is small and community-maintained; confirm whether your version uses make(), create(), address(), or a Faker method. composer show nonsapiens/realaddressfactory and the vendor source are the fastest source of truth.
Locale codes are inconsistent across tools. The package may expect nl, while Faker expects nl_NL. A mismatch often produces fallback data silently. Verify supported locales in the config or source.
Real addresses are real. Avoid sending mail, emails, or notifications to generated addresses. Treat them as test fixtures, not as disposable identities.
Uniqueness is not guaranteed. Real streets and postcodes repeat. If you add a unique index, wrap generation in fake()->unique()->realAddress() only if the provider supports it, or generate and deduplicate in PHP.
Large seeds can be slow. If the package loads a dataset per call, resolve it once or batch-generate rows. Watch memory when seeding thousands of records.
Config caching bites after publishing. Run php artisan config:clear after changing package config, especially in local and CI environments.
Auto-discovery may hide provider issues. If fake()->realAddress() is undefined, check that the service provider is discovered and that the Faker provider is registered after Faker\Generator is resolved.
Fallbacks can be silent. If a requested country has no dataset, the package may return generic data rather than throwing. Add an assertion in your own test suite if locale correctness matters.
Extension point: custom provider. If you need your own address rules, subclass the package provider or wrap the factory in an application-level helper. Bind that helper in the container so factories and seeders share one implementation.
Debugging tip: dump the raw return value once before mapping it into your model:
```
dd(RealAddressFactory::make('nl'));
```
This quickly reveals whether the result is an array, DTO, or object with accessors.
Keep it out of production dependencies unless you intentionally seed demo data in production. For normal applications, --dev is the right default.

Realaddressfactory Laravel Package