yomo/addressfactory

Creates real-world street addresses from Google Maps, to use in database seeding, unit tests, or anything else. Supports Laravel 5+, and Faker

NOTE: This package is for legacy Laravel only! Please use the newer RealAddressFactory for more recent Laravel versions!, _(*1)

RealAddress Generator

About

This Laravel 5 library creates actual, 100% real addresses, with full address details and lat/long coordinates Using the Google Maps API, these addresses can be created using the RealAddress classes, and also supports Faker, so you can use RealAddress in your database seeding!, _(*2)

Installation

Require this package with composer using the following command:, _(*3)

composer require yomo/addressfactory

Laravel 7 or higher

Please use the updated package, RealAddressFactory. This specific package is for legacy Laravel only!, _(*4)

Laravel 5.5 or higher

Execute:, _(*5)

php artisan vendor:publish --tag=yomo.realaddress

Laravel 5.4 or lower

If you are running Laravel 5.4 and below, you need to add the service provider to the providers array in config/app.php, _(*6)

Yomo\AddressFactory\AddressFactoryServiceProvider::class

Then execute:, _(*7)

php artisan vendor:publish --tag=yomo.realaddress

Google Maps API

As this library relies on Google Maps, your Google Maps API key needs to be defined in your .env file:, _(*8)

GOOGLE_MAPS_API_KEY=abcdefghijklmnopqrstuv

If you don't have an API key (they're free), get one here, _(*9)

Usage

RealAddress offers three different ways of generating real-world addresses. Each of these methods return the \Geocoder\Provider\GoogleMaps\Model\GoogleAddress class, which takes the Google Maps API response and standardises it in an easy-to-use, easy-to-read manner. As standard, RealAddress supports the generating of real addresses for the following countries:, _(*10)

• United States of America
• Great Britain
• France
• Germany
• South Africa
• Russia

You can extend RealAddress by adding additional countries in the config/realaddress.php config file. This config file also defines which cities in a given country addresses can be created for. Additional cities can be defined here., _(*11)

Faker

RealAddress provides additional functions for Faker's \Faker\Generator class instance. The code example below shows typical usage in a Factory class:, _(*12)

use Faker\Generator as Faker;

$factory->define( \App\Models\Business::class, function ( Faker $faker ) {

    /** @var \Geocoder\Provider\GoogleMaps\Model\GoogleAddress $address */
    $address = $faker->britishAddress();

    return [

        'title'              => $faker->words(2),
        'full_address'       => $address->getFormattedAddress(),
        'latitude'           => $address->getCoordinates()->getLatitude(),
        'longitude'          => $address->getCoordinates()->getLongitude()

    ];

} );

Similarly, the address can be limited to a specific city: $address = $faker->britishAddress('London');, _(*13)

or can be generated randomly between multiple-defined cities: $address = $faker->britishAddress(['London', 'Manchester']);, _(*14)

... where these cities must be defined in config/realaddress.php in order to work., _(*15)

The ready-to-use faker functions include: * britishAddress() * usaAddress() * germanAddress() * frenchAddress() * southAfricanAddress() * russianAddress(), _(*16)

If you have extended config/realaddress.php to include a new country, you can generate an address for it with:, _(*17)

    $address = $faker->realAddress('Brazil')                        # From any of the defined cities
    $address = $faker->realAddress('Brazil', 'Rio de Janiero');     # For Rio de Janiero only
    $address = $faker->realAddresss('Brazil', ['Rio de Janiero', 'Salvador'])   # Multiple cities

Using the Facade

Using the Facade allows you to generate real-world addresses at runtime, and also allows multiple addresses to be generated at once. The code examples below show typical RealAddress facade usage:, _(*18)

use Yomo\AddressFactory\Facades\RealAddress;
.
.
.
$johannesburgAddresses  = RealAddress::makeSouthAfrica(20, 'Johannesburg');     # 20 addresses for Johannesburg, South Africa
$frenchAddress          = RealAddress::makeFrance(1);                           # A single address for France
$brazilAddresses        = RealAddress::make(10, 'Brazil');                      # 10 addresses for the custom country of Brazil

Using the RealAddress class

Functionally, provides the same methods as the Facade above:, _(*19)

$f = new \Yomo\AddressFactory\RealAddress();

$southAfricanPoints = $f->makeSouthAfrica(4);                # Generates 4 locations within South Africa's major cities
$capeTownPoints     = $f->makeSouthAfrica(2, 'Cape Town');   # Generates 2 locations from Cape Town, South Africa
$multiPoints        = $f->makeSouthAfrica(3, ['Pretoria', 'Johannesburg']);

Adding new countries or cities

An example of extending the config/realaddress.php array to include Kenya, and two cities:, _(*20)

'kenya' => [
        'cities' => [ 'Nairobi', 'Mombasa' ],
    ],

Note that the cities defined here must be identifiable to Google Maps, and should ideally be spelt in their English variant., _(*21)

About the author

Stuart Steedman is the head of development at Yonder Media, a South African digital media agency operating out of Pretoria. He specialises in PHP and Laravel development, and is a speaker at tech and development related conferences., _(*22)