README

Package Status

As the original package is no longer under active development, we are updating this package just to support the latest version of Laravel. Everything else will remain the same.

Support Laravel 7.x - 12.x

Laravel World Database

This package focused on World Countries, Regions, and Cities database with locale support for Laravel.

Conceptions

There are 5 main objects in this package.

World: the earth world.
Continent: 7 continent
Country: 248 countries
Division: Divisions such as state/province.
City: the last level of region, some cities up to Country, some up to Division.

Attributes

Common attributes:

name: Common name of region(english).
full_name: Full name or official name(english).
code: ISO-3166-1-alpha2/ISO-3166-2 code
local_name: translation of Common name
local_full_name: translation of full name
local_alias: alias in different language
local_abbr: Abbreviation

Country spec attributes:

emoji: Emoji flag of country
capital: Captial of this country
code_alpha3: Code of ISO-3166-1-alpha3
currency_code: ISO-4177 Currency Code, e.g. USD, CNY
currency_name: ISO-4177 Currency Name,
local_currency_name: ISO-4177 Currency name in locale

Example:

use Khsing\World\World;
$china = World::getByCode('cn');
$china->setLocale('zh-cn');
$china->name; // China
$china->local_name; // 中国
$china->full_name; // People's Republic of China
$china->local_full_name; // 中华人民共和国
$china->emoji; // 🇨🇳
$china->callingcode; // 86
$china->code; // CN
$china->code_alpha3; // CHN
$china->has_division; // true
$china->currency_code; // CNY
$china->currency_name; // Yuan Renminbi
$china->local_currency_name; // 人民币

Localization

Right now, only English(default and fallback) and Chinese-Simp zh-cn are supported. Locale settings is following Laravel project settings in config/app.php.

Setup

composer require

composer require appolous/world

Add Service Provider into config/app.php, (Only required before Laravel 5.5)

'providers' => [
    // ...
    Khsing\World\WorldServiceProvider::class,
]

Publish and init

php artisan vendor:publish --force --provider="Khsing\World\WorldServiceProvider"
composer dump-autoload
php artisan world:init

Usage

get all Continent

use Khsing\World\World;

World::Continents()

get all Countries

use Khsing\World\World;

World::Countries()

get country/city/division by code

use Khsing\World\World;

World::getByCode('cn'); // iso-3166 alpha 2 code
World::getByCode('chn'); // iso-3166 alpha 3 code
World::getByCode('cn-11'); // Beijing

get countries belong to a continent

use Khsing\World\Models\Continent;

$asia = Continent::getByCode('AS');
$countries = $asia->countries()->get();
// or use children method
$countries = $asia->children();

get continent or parent

$china = Country::getByCode('cn');
$asia = $china->parent();

get division/state/province via Conutry

$china = Country::getByCode('cn');
$provinces = $china->divisions()->get()
// or use children method
$provinces = $china->children();

get cities via Country or Division.

$china = Country::getByCode('cn');
// check has_division to determine next level is division or city.
$china->has_division; // true, otherwise is false
$regsions = $china->children();

Contributions

If you want contribute to this library, issue and pr are welcome. please following those steps.

start a new laravel project and install this library.
install orangehill/iseed.
modify datas via sql.
generate seeds via artisan iseed world_cities,world_cities_locale,world_continents,world_continents_locale,world_countries,world_countries_locale,world_divisions,world_divisions_locale
replace delete() with truncate(), cd database/seeders/ && sed -i 's/->delete()/->truncate()/g' World*.php
copy seeds files into library.
commit your work. ;)

TODO

change the way to seed data, eg. loading data from json?
add front-end support
find a way to update dataset

Data Sources

ISO 639-1 Standard Language Codes: language codes
ISO 639-1 standard language codes: language codes
United Nations Statistics Division: Standard country or area codes for statistical use (M49): ISO-3166-alpha3 code and country list.
ISO 3166-2: main data source

Thanks

About

This package published under MIT license. If you have any question or suggestion, please feel free to submit a issue, or email me Guixing<khsing.cn(AT)gmail.com>.

Have a nice day.

appolous / world

Maintainers

Details