Skip to content
provide countries, states, and cities relations and database.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
database Latest updates Oct 12, 2019
src Replace deprecates string helpers with Str class Sep 23, 2019
tests * rename .php_cs.dist to .php_cs Feb 9, 2019
.gitignore test Apr 8, 2017
.php_cs * rename .php_cs.dist to .php_cs Feb 9, 2019
.travis.yml fix travis CI Feb 9, 2019
composer.json Merge pull request #20 from sitehandy/master Jan 10, 2020
composer.lock change 兰州市 to 兰州 Nov 29, 2017
phpunit.xml.dist * rename .php_cs.dist to .php_cs Feb 9, 2019 fix travis CI Feb 9, 2019

Laravel World Database

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


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.


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


use Khsing\World\World;
$china = World::getByCode('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; // 人民币


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.


  • composer require
composer require khsing/world
  • Add Service Provider into config/app.php
'providers' => [
    // ...
  • Publish and init
php artisan vendor:publish --force --provider="Khsing\World\WorldServiceProvider"
composer dump-autoload
php artisan world:init


  • get all Continent
use Khsing\World\World;

  • get all Countries
use Khsing\World\World;

  • 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();


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

  1. start a new laravel project and install this library.
  2. install orangehill/iseed.
  3. modify datas via sql.
  4. 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
  5. replace delete() with truncat(), cd database/seeds/ && sed -i 's/->delete()/->truncat()/g' World*.php
  6. copy seeds files into library.
  7. commit your work. ;)


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



This package published under MIT license. If you have any question or suggestion, please feel free to submit a issue, or email me Guixing<>.

Have a nice day.

You can’t perform that action at this time.