PHPackages                             khsing/world - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. khsing/world

ActiveLibrary[Database & ORM](/categories/database)

khsing/world
============

Provide countries, states, and cities relations database.

v10.0.0(2mo ago)461146.3k↑75%101[10 issues](https://github.com/khsing/laravel-world/issues)1MITPHPPHP ^8.0CI passing

Since Apr 5Pushed 2mo ago18 watchersCompare

[ Source](https://github.com/khsing/laravel-world)[ Packagist](https://packagist.org/packages/khsing/world)[ RSS](/packages/khsing-world/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (7)Versions (20)Used By (1)

Laravel World Database
======================

[](#laravel-world-database)

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

Conceptions
-----------

[](#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

[](#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

[](#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
-----

[](#setup)

- `composer require`

```
composer require khsing/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
-----

[](#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
-------------

[](#contributions)

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](https://github.com/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 `truncate()`, `cd database/seeders/ && sed -i 's/->delete()/->truncate()/g' World*.php`
6. copy seeds files into library.
7. commit your work. ;)

TODO
----

[](#todo)

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

Data Sources
------------

[](#data-sources)

- [ISO 639-1 Standard Language Codes](https://www.knowledgebase-script.com/kb/article/iso-639-1-standard-language-codes-255.html): language codes
- [ISO 639-1 standard language codes](https://www.andiamo.co.uk/resources/iso-language-codes/): language codes
- [United Nations Statistics Division: Standard country or area codes for statistical use (M49)](https://unstats.un.org/unsd/methodology/m49/overview/): ISO-3166-alpha3 code and country list.
- [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2): main data source

Thanks
------

[](#thanks)

- [moolighty/geo](https://github.com/moolighty/geo)
- [mledoze/countries](https://github.com/mledoze/countries)
- [cn/GB2260](https://github.com/cn/GB2260)

About
-----

[](#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.

###  Health Score

65

—

FairBetter than 99% of packages

Maintenance86

Actively maintained with recent releases

Popularity54

Moderate usage in the ecosystem

Community31

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 64.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~192 days

Recently: every ~457 days

Total

18

Last Release

69d ago

Major Versions

v5.x-dev → v6.02021-03-03

v6.x-dev → v7.02021-03-08

v7.x-dev → v8.02021-03-08

v8.1 → v9.02022-05-13

v9.0 → v10.0.02026-03-11

PHP version history (6 changes)v0.1PHP >=5.5.9

v0.2PHP >=5.6.4

v0.3PHP >=7.0

v0.9PHP >=7.1

v9.0PHP >7.3|^8.0

v10.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/c68396cee81eeadca4e4f808c719710b8c2eebb6b0232733fd3de39d8d37b9ad?d=identicon)[khsing](/maintainers/khsing)

---

Top Contributors

[![khsing](https://avatars.githubusercontent.com/u/40765?v=4)](https://github.com/khsing "khsing (38 commits)")[![rbridge](https://avatars.githubusercontent.com/u/916258?v=4)](https://github.com/rbridge "rbridge (2 commits)")[![mednasserallah](https://avatars.githubusercontent.com/u/23226046?v=4)](https://github.com/mednasserallah "mednasserallah (2 commits)")[![uovidiu](https://avatars.githubusercontent.com/u/76910?v=4)](https://github.com/uovidiu "uovidiu (2 commits)")[![Human018](https://avatars.githubusercontent.com/u/8413094?v=4)](https://github.com/Human018 "Human018 (2 commits)")[![geoffreyvanwyk](https://avatars.githubusercontent.com/u/194185?v=4)](https://github.com/geoffreyvanwyk "geoffreyvanwyk (2 commits)")[![nauman-coeus](https://avatars.githubusercontent.com/u/42341849?v=4)](https://github.com/nauman-coeus "nauman-coeus (1 commits)")[![nbyloff](https://avatars.githubusercontent.com/u/517059?v=4)](https://github.com/nbyloff "nbyloff (1 commits)")[![sitehandy](https://avatars.githubusercontent.com/u/22477788?v=4)](https://github.com/sitehandy "sitehandy (1 commits)")[![yangcaiop](https://avatars.githubusercontent.com/u/37070477?v=4)](https://github.com/yangcaiop "yangcaiop (1 commits)")[![abhishek6262](https://avatars.githubusercontent.com/u/16699718?v=4)](https://github.com/abhishek6262 "abhishek6262 (1 commits)")[![yswtrue](https://avatars.githubusercontent.com/u/1270490?v=4)](https://github.com/yswtrue "yswtrue (1 commits)")[![amirolzolkifli](https://avatars.githubusercontent.com/u/6100743?v=4)](https://github.com/amirolzolkifli "amirolzolkifli (1 commits)")[![balduinofernando](https://avatars.githubusercontent.com/u/20538071?v=4)](https://github.com/balduinofernando "balduinofernando (1 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![Kauto](https://avatars.githubusercontent.com/u/6749584?v=4)](https://github.com/Kauto "Kauto (1 commits)")[![mokhosh](https://avatars.githubusercontent.com/u/6499685?v=4)](https://github.com/mokhosh "mokhosh (1 commits)")

---

Tags

citycontinentcountrydatabasedivisionlaravelregionstatetranslationworldcountrycityworldregion

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/khsing-world/health.svg)

```
[![Health](https://phpackages.com/badges/khsing-world/health.svg)](https://phpackages.com/packages/khsing-world)
```

###  Alternatives

[epigra/trgeozones

Türkiye İl İlçe Semt Muhit Mahalle ve Posta Kodları Laravel Paketi. Adds Turkish Geographical Zones Support to your project including Cities, Districts and Countries in Turkish

8820.3k](/packages/epigra-trgeozones)[nevadskiy/laravel-geonames

Populate your database using the GeoNames service.

2715.1k](/packages/nevadskiy-laravel-geonames)[woenel/prpcmblmts

Philippines region, province, cities/municipalities and barangays Laravel migration and table seeder.

2818.3k](/packages/woenel-prpcmblmts)[tomatophp/filament-locations

Database Seeds for Countries / Cities / Areas / Languages / Currancy with ready to use resources for FilamentPHP

2320.8k6](/packages/tomatophp-filament-locations)[salibhdr/typhoon-iran-cities

A laravel package for importing all regions such as provinces, counties, cities, city districts, rural districts and villages of iran into database accurately

6121.0k](/packages/salibhdr-typhoon-iran-cities)[yurtesen/geonames

Geonames importer and models for Eloquent ORM

311.7k](/packages/yurtesen-geonames)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)