human018/laravel-earth

A multilingual package to populate continents, countries, divisions and cities for planet earth

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact
7. Acknowledgements

About The Project

A multilingual Laravel package to populate continents, countries, regions, cities, languages and currencies for planet earth.

Built With

• PHP
• Laravel

Getting Started

This project is built using Laravel 8 and is not currently backwards compatible with older versions.

Prerequisites

• PHP 7.4
• Laravel 8, 9, 10 or 11
• Guzzle
• ZipArchive
• Countrylayer API

Because this library uses an NPM package as one of it's data sources, you will need to allow composer to download an NPM package. To do so add the following property (or append to the already existing property) to the repositories array/object in your composer.json file.

    "repositories": [
        {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    ]

API Access

You will require an API key with countrylayer in order to use its services. A free key is available and all that will be required for the seed. Once you have your API key add it to your .env file.

COUNTRY_LAYER_API=XXX

Installation

1. Using composer install the package to your project.

   composer require human018/laravel-earth

2. Run database migration.

   php artisan migrate

3. This package seeds the database with various sources (listed below) so an initialisation script need to be run in order to access these third-party sources and seed your database.

   php artisan earth:init

4. (Optional) If you want to seed all the cities in a certain country pass in the country code. Note that this may take a long time depending on the country you're seeding.

   php artisan earth:init --country=au

5. (Optional) You can also seed all major cities (over 15,000 in pop.).

   php artisan earth:init --cities=major

Usage

All models are located in the same namespace and can be imported into your local project.

use Human018\LaravelEarth\Models\Continent;
use Human018\LaravelEarth\Models\Country;
use Human018\LaravelEarth\Models\Region;
use Human018\LaravelEarth\Models\City;
use Human018\LaravelEarth\Models\Language;
use Human018\LaravelEarth\Models\Currency;
use Human018\LaravelEarth\Models\Timezone;
use Human018\LaravelEarth\Models\TimezoneUTC;

A couple of helpful methods for finding the correct resource are included. This means the resource name or code can be used to quickly locate a resource. Additionally, relationships between models are connected in a standard way and can be chained like usual.

// eg 1. Retrieve country by code 
$country = Country::code('au');
echo $country->regions->count();
// Returns '8'

// eg 2. You can pass in the Code in lower or upper case
$country = Country::code('AU');

// Eg 3. You can also search by name
$region = Region::name('New South Wales');
echo $region->country->name;
// Returns 'Australia'

echo $region->country->capital->name;
// Returns 'Canberra'

Retrieving timezones are slightly more complicated. Currently timezones are connected to Countries rather than Regions or Cities. Because a country can have multiple UTC zones, and in turn those zones can belong to the same Timezone, retrieving the relationship just requires us to use the unique query modifier.

$country = Country::code('ca'); // Canada
$country->timezones->pluck('label');
// Returns duplicates because it's unique UTC zones
// belong to many of the same Timezones

$country->timezones->unique()->pluck('label');
// Returns only unique timezones

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Simon Woodard - @human018

Project Link: https://github.com/Human018/laravel-earth

Acknowledgements

• countrylayer
• country-region-data
• GeoNames