PHPackages                             sitehandy/laravel-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. sitehandy/laravel-world

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

sitehandy/laravel-world
=======================

Provide countries, states, and cities relations database with Laravel 9-12 support.

v1.0.0(8mo ago)0105MITPHPPHP ^8.1

Since Aug 16Pushed 6mo agoCompare

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

READMEChangelogDependencies (3)Versions (2)Used By (0)

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

[](#sitehandy-laravel-world-database)

[![Latest Stable Version](https://camo.githubusercontent.com/3a05acbfeb232067ecdaf0dd10f98d9e9928b1034974d45e4ca0d1665211b278/68747470733a2f2f706f7365722e707567782e6f72672f7369746568616e64792f6c61726176656c2d776f726c642f762f737461626c65)](https://packagist.org/packages/sitehandy/laravel-world)[![License](https://camo.githubusercontent.com/6270670bf16a8f90caa3c493e123e7c3352ed1586e3d9cd9958d659885dba456/68747470733a2f2f706f7365722e707567782e6f72672f7369746568616e64792f6c61726176656c2d776f726c642f6c6963656e7365)](https://packagist.org/packages/sitehandy/laravel-world)[![Laravel](https://camo.githubusercontent.com/1d554afeb4fd9101e5101a8d8474a878980d2aa6e3e5b573b971c15d27cd7130/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d392532422d6f72616e67652e737667)](https://laravel.com)

This package provides World Countries, Regions, and Cities database with locale support for Laravel 9-12.

Credits
-------

[](#credits)

This package is a fork of the excellent [khsing/laravel-world](https://github.com/khsing/laravel-world) package by [Guixing Bai](https://github.com/khsing). We extend our gratitude to the original author for creating this valuable resource.

### What's Changed in This Fork

[](#whats-changed-in-this-fork)

- **Updated namespace**: Changed from `Khsing\World` to `Sitehandy\World`
- **Laravel 9-12 compatibility**: Full support with modern Laravel syntax
- **PHP 8.1+ support**: Updated to support modern PHP versions
- **Database modernization**:
    - Updated all migrations to use `Schema::dropIfExists()` instead of deprecated `Schema::drop()`
    - Modernized primary key definitions using `id()` method
    - Enhanced foreign key constraint handling
- **Code quality improvements**: All deprecated Laravel features updated
- **Package optimization**: Configured for professional Packagist publishing
- **Maintained by**: Sitehandy Solutions
- **Semantic versioning**: Starting from version 1.0.0

Version
-------

[](#version)

Current version: **1.0.0**

We follow [Semantic Versioning](https://semver.org/) for all releases:

- **Major** (1.x.x): Breaking changes
- **Minor** (x.1.x): New features, backward compatible
- **Patch** (x.x.1): Bug fixes, backward compatible

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 Sitehandy\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`.

Requirements
------------

[](#requirements)

- **PHP**: 8.1 or higher (required for Laravel 11+ compatibility)
- **Laravel**: 9.0 or higher
    - ✅ Laravel 9.x - Full support
    - ✅ Laravel 10.x - Full support
    - ✅ Laravel 11.x - Full support
    - ✅ Laravel 12.x - Full support
- **Database**: MySQL 5.7+, PostgreSQL 10+, SQLite 3.8+, SQL Server 2017+

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require sitehandy/laravel-world
```

### Step 2: Service Provider (Laravel < 5.5 only)

[](#step-2-service-provider-laravel--55-only)

For Laravel 5.5+, the service provider is automatically registered via package discovery.

For older versions, add to `config/app.php`:

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

### Step 3: Publish and Initialize

[](#step-3-publish-and-initialize)

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

**Note**: The `world:init` command will create the necessary database tables and seed them with world data. This may take a few minutes to complete.

Technical Improvements
----------------------

[](#technical-improvements)

This package has been thoroughly modernized for Laravel 9-12 compatibility:

### Database Migrations & Seeders

[](#database-migrations--seeders)

- ✅ **Modern Schema Methods**: All migrations updated to use `Schema::dropIfExists()` instead of deprecated `Schema::drop()`
- ✅ **Primary Key Modernization**: Updated from `bigIncrements()` to modern `id()` method
- ✅ **Foreign Key Optimization**: Enhanced foreign key constraint handling for better performance
- ✅ **Cross-Database Compatibility**: Tested with MySQL, PostgreSQL, SQLite, and SQL Server
- ✅ **Strict Type Declarations**: Added `declare(strict_types=1)` to all migration and seeder files
- ✅ **Return Type Hints**: All migration and seeder methods now have proper `: void` return types
- ✅ **Modern Import Statements**: Updated seeders to use `use Illuminate\Support\Facades\DB;` instead of `\DB::`
- ✅ **Consistent Code Formatting**: Standardized bracket styles and spacing across all database files
- ✅ **Professional Documentation**: Added comprehensive DocBlocks to all migration and seeder classes
- ✅ **Laravel 12 Compliance**: All database files follow the latest Laravel 12 best practices and conventions

### Code Quality & Best Practices

[](#code-quality--best-practices)

- ✅ **Namespace Consistency**: Complete migration from `Khsing\World` to `Sitehandy\World`
- ✅ **Laravel Standards**: All deprecated features updated to current Laravel standards
- ✅ **PHP 8.1+ Features**: Leveraging modern PHP capabilities for better performance
- ✅ **Package Optimization**: Configured for professional Packagist publishing standards
- ✅ **Strict Type Declarations**: Added `declare(strict_types=1)` to all PHP files
- ✅ **Modern Return Types**: All methods now have proper return type declarations
- ✅ **PSR-4 Autoloading**: Full compliance with PSR-4 autoloading standards
- ✅ **Typed Properties**: Modern PHP 8.1+ typed properties implementation
- ✅ **Null Coalescing**: Leveraging null coalescing operators for cleaner code
- ✅ **Union Types**: Using PHP 8.0+ union types where appropriate
- ✅ **Arrow Functions**: Modern arrow function syntax for improved readability
- ✅ **Comprehensive DocBlocks**: Professional documentation for all classes and methods
- ✅ **Laravel Eloquent Best Practices**: Proper relationship type hints and return types
- ✅ **Error Handling**: Improved exception handling with typed exceptions
- ✅ **Code Organization**: Clean separation of concerns and single responsibility principle

### Compatibility Testing

[](#compatibility-testing)

- ✅ **Laravel 9.x**: Full compatibility verified
- ✅ **Laravel 10.x**: Full compatibility verified
- ✅ **Laravel 11.x**: Full compatibility verified
- ✅ **Laravel 12.x**: Full compatibility verified
- ✅ **PHP 8.1-8.3**: Tested across all supported PHP versions

Usage
-----

[](#usage)

### Basic Usage Examples

[](#basic-usage-examples)

#### Get all Continents

[](#get-all-continents)

```
use Sitehandy\World\World;

$continents = World::Continents();
```

#### Get all Countries

[](#get-all-countries)

```
use Sitehandy\World\World;

$countries = World::Countries();
```

#### Get Country/City/Division by Code

[](#get-countrycitydivision-by-code)

```
use Sitehandy\World\World;

$china = World::getByCode('cn');     // ISO-3166 alpha 2 code
$china = World::getByCode('chn');    // ISO-3166 alpha 3 code
$beijing = World::getByCode('cn-11'); // Beijing
```

#### Get Countries by Continent

[](#get-countries-by-continent)

```
use Sitehandy\World\Models\Continent;

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

#### Get Parent (Continent/Country)

[](#get-parent-continentcountry)

```
use Sitehandy\World\Models\Country;

$china = Country::getByCode('cn');
$asia = $china->parent(); // Returns the continent
```

#### Get Divisions/States/Provinces

[](#get-divisionsstatesprovinces)

```
use Sitehandy\World\Models\Country;

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

#### Get Cities

[](#get-cities)

```
use Sitehandy\World\Models\Country;

$china = Country::getByCode('cn');
// Check has_division to determine if next level is division or city
if ($china->has_division) {
    $regions = $china->children(); // Returns divisions/provinces
} else {
    $cities = $china->children(); // Returns cities directly
}
```

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)

Changelog
---------

[](#changelog)

### Version 1.0.0 (2025-08-16)

[](#version-100-2025-08-16)

- **Initial release** of sitehandy/laravel-world package
- **Breaking change**: Namespace changed from `Khsing\World` to `Sitehandy\World`
- **Added**: Full Laravel 9-12 compatibility with modern syntax
- **Added**: PHP 8.1+ support with strict type requirements
- **Updated**: Database migrations to use modern Laravel syntax
    - Replaced deprecated `Schema::drop()` with `Schema::dropIfExists()`
    - Updated `increments()` method to modern `id()` method
    - All foreign key constraints modernized
- **Enhanced**: Package configuration optimized for Packagist publishing
- **Improved**: All deprecated Laravel features updated to current standards
- **Modernized**: Complete code quality overhaul following Laravel best practices
    - Added strict type declarations (`declare(strict_types=1)`) to all PHP files
    - Implemented proper return type hints for all methods
    - Added comprehensive PHPDoc blocks with parameter and return types
    - Leveraged modern PHP 8.1+ features (typed properties, union types, null coalescing)
    - Applied Laravel Eloquent best practices with proper relationship type hints
    - Improved error handling with typed exceptions
    - Enhanced code organization following single responsibility principle
- **Database Modernization**: Complete overhaul of all migration and seeder files
    - Updated all migrations to use modern Laravel 12 syntax and conventions
    - Replaced deprecated methods with current Laravel standards
    - Added strict typing and return type declarations to all database files
    - Improved import statements and code formatting consistency
    - Enhanced documentation with professional DocBlocks
- **Verified**: Complete compatibility testing across Laravel 9, 10, 11, and 12
- **Maintained**: All original functionality from khsing/world with enhanced reliability and performance

Contributing
------------

[](#contributing)

We welcome contributions! Please feel free to submit issues and pull requests.

### Development Setup

[](#development-setup)

If you want to contribute to this library, issues and PRs are welcome. Please follow these steps:

1. Start a new Laravel project and install this library
2. Install [orangehill/iseed](https://github.com/orangehill/iseed)
3. Modify data 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 seed files into the library
7. Commit your work

License
-------

[](#license)

This package is published under the MIT license.

Support
-------

[](#support)

If you have any questions or suggestions, please feel free to:

- Submit an issue on GitHub
- Email us at

About Sitehandy Solutions
-------------------------

[](#about-sitehandy-solutions)

Sitehandy Solutions is committed to maintaining and improving this package. We appreciate the original work by Guixing Bai and the community.

Have a nice day! 🌍

###  Health Score

35

—

LowBetter than 80% of packages

Maintenance64

Regular maintenance activity

Popularity10

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 59.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

Unknown

Total

1

Last Release

269d ago

### Community

Maintainers

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

---

Top Contributors

[![khsing](https://avatars.githubusercontent.com/u/40765?v=4)](https://github.com/khsing "khsing (38 commits)")[![sitehandy](https://avatars.githubusercontent.com/u/22477788?v=4)](https://github.com/sitehandy "sitehandy (6 commits)")[![rbridge](https://avatars.githubusercontent.com/u/916258?v=4)](https://github.com/rbridge "rbridge (2 commits)")[![geoffreyvanwyk](https://avatars.githubusercontent.com/u/194185?v=4)](https://github.com/geoffreyvanwyk "geoffreyvanwyk (2 commits)")[![uovidiu](https://avatars.githubusercontent.com/u/76910?v=4)](https://github.com/uovidiu "uovidiu (2 commits)")[![mednasserallah](https://avatars.githubusercontent.com/u/23226046?v=4)](https://github.com/mednasserallah "mednasserallah (2 commits)")[![Human018](https://avatars.githubusercontent.com/u/8413094?v=4)](https://github.com/Human018 "Human018 (2 commits)")[![nbyloff](https://avatars.githubusercontent.com/u/517059?v=4)](https://github.com/nbyloff "nbyloff (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)")[![nauman-coeus](https://avatars.githubusercontent.com/u/42341849?v=4)](https://github.com/nauman-coeus "nauman-coeus (1 commits)")

---

Tags

countrycityworldregion

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[khsing/world

Provide countries, states, and cities relations database.

461146.3k1](/packages/khsing-world)[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)

PHPackages © 2026

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