lwwcas/laravel-countries

Laravel Countries is an Eloquent-first package that models the entire world as native Laravel relationships: ISO 3166 codes (Alpha-2, Alpha-3, numeric), international phone codes, currencies, national flags (SVG, emoji, HEX/RGB colors), GeoJSON borders, geographic coordinates, demographics, GDP, independence dates and region hierarchies — all translated into 9 languages and seeded straight into your own database.

No external APIs. No JSON files to fetch, parse and cache yourself. No stale array copy-pasted from a gist. Install the package, run one Artisan command, and countries behave like any other Eloquent model in your app — queryable, relatable, cacheable, testable.

⭐ Enjoying this package?

If Laravel Countries saved you some time, consider leaving a star on the repo. It's free, takes two seconds, and it's the main way other developers find this project.

👉 Star Laravel Countries on GitHub

On this page

Why Laravel Countries? • Features • Data Model • Available Languages • Getting Started • Usage • Testing • Contributing

🤔 Why Laravel Countries?

Most "country list" packages for PHP give you a static array or a JSON file with a name and a two-letter code — fine for a dropdown, useless for anything real.

Laravel Countries is built for applications that actually do something with country data:

• It's a real Eloquent model, not a helper function. Country::whereIso('BR')->first() behaves like any other model — relationships, scopes, eager loading, caching, all included.
• It lives in your database, not in a vendor JSON file. Link a country_id foreign key to users, addresses, orders — whatever your app needs — with a normal Eloquent relationship.
• It's translated, not just in English. Country and region names ship pre-translated in 9 languages, reviewed by native-speaking contributors — not machine-translated on the fly.
• It's geographic, not just alphabetical. GeoJSON borders and coordinates mean you can actually draw a map, not just print a list.
• It's tested. CI-checked against Laravel 11, 12 and 13 with a full Pest suite — not a "works on my machine" side project.
• It only takes up the space you actually need. Install just the languages your app uses — add or drop languages later without touching the rest of your data, so your database never carries translations you'll never query.

✨ Features

• 🗄️ Eloquent-native country model — Country:: behaves like any other Laravel model: scopes, relationships, eager loading
• 🌐 ISO 3166 codes — Alpha-2, Alpha-3 and numeric, all queryable (whereIso, whereIsoAlpha3, whereIsoNumeric)
• ☎️ International phone codes — validate and query by dialing code (wherePhoneCode)
• 💱 Currency data — query countries by currency
• 🏳️ Flags in 3 formats — SVG, emoji, and flag colors in HEX/RGB
• 🗺️ GeoJSON borders + coordinates — precise geographic data, ready for maps
• 📊 Demographics & economics — population, area (km²), GDP
• 🕊️ Independence dates & bordering countries
• 🌍 Region hierarchy — continents and regions, translated too
• 🗣️ 9 languages built-in — no separate i18n package needed (see table below)
• 🧩 Install only the languages you need — pick them at install time, then add or remove languages whenever you want, keeping your database lean instead of seeding all 9 by default
• ⚡ One Artisan command to install and seed everything, idempotent and CI-safe
• ✅ Tested with Pest, CI-checked against Laravel 11, 12, and 13
• 🚫 Zero external API calls — everything is seeded once, queried locally, forever

🗺️ Data Model

A quick look at what's on the Country model (full reference in the Method Listing docs):

🌍 Available Languages

Every country and region name is translated in all 9 languages below — the table shows how many countries have that language as an official/native language, not translation coverage (translation coverage is 100% across all languages).

You don't have to install all 9. Pick only the languages your app actually serves at install time, and add or remove languages later — Laravel Countries manages the translation rows for you, so your database only ever stores what you're using.

Missing a language? Contributions are welcome — the guide explains how translations get reviewed.

🚀 Getting Started

Install via Composer:

composer require lwwcas/laravel-countries

Run the installer:

php artisan w-countries:install

That's it — the countries table is seeded and ready to query.

Production / CI (Laravel 11, 12, and 13)

In production, use --force to skip confirmation prompts:

php artisan w-countries:install --force

If migrations already ran during deploy and you only need the data:

php artisan w-countries:seed --languages=en,pt,es

To list the equivalent manual db:seed commands:

php artisan w-countries:seed --show-commands

See the Seeders documentation for the full production guide and manual seeder class reference.

🧩 Manage languages anytime

Only need Portuguese and English today? Only seed those two — there's no need to carry all 9 languages in your database if your app doesn't use them:

php artisan w-countries:seed --languages=en,pt

Adding a new market later (say, Spanish) doesn't mean starting over — install the new language on top of what you already have. The same applies in reverse: if a language is no longer needed, you can remove it without touching the rest of your country data.

Full add/remove workflow and command reference → Available Languages docs

🧑‍💻 Usage & Query Examples

Basic lookups:

use Lwwcas\LaravelCountries\Models\Country;

Country::whereIso('BR')->first();
Country::whereIsoAlpha3('BRA')->first();
Country::whereSlug('brasil')->first();

Flags — SVG, emoji, and colors:

$country = Country::whereIso('FR')->first();

$country->flag_svg;    // SVG markup
$country->flag_emoji;  // 🇫🇷
$country->flag_colors; // ['#0055A4', '#FFFFFF', '#EF4135']

Phone codes & currency:

Country::wherePhoneCode('+55')->first();
Country::whereGdp(1000)->get(); // GDP in billions USD

Geographic data — coordinates & GeoJSON:

$country = Country::whereIso('JP')->first();

$country->latitude;
$country->longitude;
$country->geojson; // ready to drop into any map library

Language & region:

Country::whereLanguage('en')->get();
Country::whereLanguages(['en', 'fr'])->get();

Looking for relationships, scopes, config, or translation helpers? → See the full documentation

🧪 Testing

composer test

🤝 Contributing

Contributions, translations, and bug reports are very welcome. Please read CONTRIBUTING.md before opening a pull request.

👥 Credits

• Lucas Duarte
• Saad Batwa — detailed review and corrections of Arabic country translations (PR #45)
• İlyas Özkurt — Turkish language translations (PR #36)
• All Contributors

📄 License

The MIT License (MIT). Please see LICENSE.md for more information.