README

Lightweight Laravel package to seed Countries, States and Cities with model relationships and optional country flags.

What you'll get:

• Seeders and migrations for Country, State and City models
• Pre-defined model relationships (Country -> State -> City)
• Optional ISO codes (iso2, iso3), numeric code, phone code and country flags

Why use it?

• Open source and free
• Easy to install and modify
• Works out of the box with Laravel

Requirements

• PHP 8.1+ (or the version required by your Laravel application)
• Laravel 9 / 10 / 11

Quick installation

Install via Composer:

composer require zalanihir/country-state-city

Register the service provider (only if your Laravel version requires manual registration):

• Laravel 9 / 10: add this to config/app.php providers array:

\Nihir\CountryStateCity\CountryStateCityServiceProvider::class,

• Laravel 11: add this to bootstrap/app/providers.php (if applicable):

\Nihir\CountryStateCity\CountryStateCityServiceProvider::class,

Publish package files and flags:

php artisan vendor:publish --provider="Nihir\CountryStateCity\CountryStateCityServiceProvider"
php artisan csc:publish-flags

Run migrations and seeders:

php artisan migrate

Add the seeder call to DatabaseSeeder.php:

$this->call(CountryStateCityTableSeeder::class);

Then run:

php artisan db:seed

Notes

• If you already have Country/State/City models or migrations in your project, remove or rename them to avoid conflicts before running the package migrations.
• The package fetches flags from https://flagsapi.com/ (64px). If some flags are missing you can contribute missing images in the flags/ folder.

Usage example (display flags):

use App\Models\Country;

$countries = Country::all();

foreach ($countries as $country) {
    echo '<img src="'.asset('flags/'.$country->iso2.'.png').'" alt="'.$country->name.'" />';
}

Support

If you find issues or need help, email: testnihir@gmail.com

Connect with me

Contributors

Thanks to everyone who contributed!

Zala Nihir

Want to contribute? See CONTRIBUTING.md.