README

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

Credits

This package is a fork of the excellent khsing/world package by Guixing Bai. We extend our gratitude to the original author for creating this valuable resource.

What's 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

Current version: 1.0.0

We follow Semantic Versioning 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

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

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

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

Step 1: Install via Composer

composer require sitehandy/laravel-world

Step 2: Service Provider (Laravel < 5.5 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

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

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

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

✅ 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

✅ 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

Basic Usage Examples

Get all Continents

use Sitehandy\World\World;

$continents = World::Continents();

Get all Countries

use Sitehandy\World\World;

$countries = World::Countries();

Get Country/City/Division 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

use Sitehandy\World\Models\Continent;

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

Get Parent (Continent/Country)

use Sitehandy\World\Models\Country;

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

Get Divisions/States/Provinces

use Sitehandy\World\Models\Country;

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

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

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

Changelog

Version 1.0.0 (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

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

Development Setup

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

Start a new Laravel project and install this library
Install orangehill/iseed
Modify data 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 seed files into the library
Commit your work

License

This package is published under the MIT license.

Support

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

Submit an issue on GitHub
Email us at support@sitehandy.com

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! 🌍

sitehandy / laravel-world

Maintainers

Details