Provide countries, states, and cities models database.

v1.0 2020-07-09 18:54 UTC

This package is auto-updated.

Last update: 2024-06-16 23:36:10 UTC


Lumen World Models for Laravel World Database

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


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 Lumen project settings in config/app.php.


  • composer require
composer require brianfp/lumen-world


  • 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.