README

A Laravel package that provides comprehensive data for every country — codes, names, currencies, languages, capitals, regions, demonyms, translations, and more. Laravel 11+ supported.

What's New in v3.0.0

Updated data source — Country data is now compiled from the REST Countries v3.1 dataset.
New search methods — Search by name, language, capital, demonym, translation, and independence status.
Unified code lookup — New getByCode() method auto-detects cca2, cca3, ccn3, or cioc codes.
Deprecations — getByAlpha2Code(), getByAlpha3Code(), and getByNumericCode() are deprecated in favor of getByCode(). They still work but will trigger E_USER_DEPRECATED notices.
PHPUnit 12 compatibility — Test suite updated.

Install

composer require opheus2/laravel-countries

Upgrading from v2.x

Replace deprecated method calls:

use Orpheus\LaravelCountries\Facades\Countries;

// Before (deprecated)
$country = Countries::getByAlpha2Code('CA');
$country = Countries::getByAlpha3Code('CAN');
$country = Countries::getByNumericCode(124);

// After
$country = Countries::getByCode('CA');
$country = Countries::getByCode('CAN');
$country = Countries::getByCode(124);

The deprecated methods still function but will emit E_USER_DEPRECATED warnings and will be removed in a future major release.

Usage

Lookup by Code

The getByCode() method auto-detects the code type:

use Orpheus\LaravelCountries\Facades\Countries;

$country = Countries::getByCode('CA');    // 2-letter (cca2)
$country = Countries::getByCode('CAN');   // 3-letter (cca3) or CIOC
$country = Countries::getByCode(124);     // Numeric (ccn3)
$country = Countries::getByCode('124');   // Numeric as string

Search by Name

use Orpheus\LaravelCountries\Facades\Countries;

// Partial match (searches common, official, and native names)
$countries = Countries::getByName('united');

// Exact match on common or official name
$countries = Countries::getByFullName('Canada');
$countries = Countries::getByFullName('United States of America');

Search by Language

use Orpheus\LaravelCountries\Facades\Countries;

// By language code
$countries = Countries::getByLanguage('fra');

// By language name (partial match)
$countries = Countries::getByLanguage('French');
$countries = Countries::getByLanguage('Spanish');

Search by Capital

use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByCapital('Ottawa');
$countries = Countries::getByCapital('Wash');   // Partial match

Search by Demonym

use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByDemonym('Canadian');
$countries = Countries::getByDemonym('peruvian');  // Case-insensitive

Search by Translation

use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByTranslation('Alemania');   // Germany in Spanish
$countries = Countries::getByTranslation('Saksamaa');    // Germany in Estonian

Search by Currency

use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByCurrency('CAD');              // By currency code
$countries = Countries::getByCurrency('Canadian dollar');  // By currency name

Filter by Region / Subregion

use Orpheus\LaravelCountries\Facades\Countries;

$countries = Countries::getByRegion(Countries::$REGION_AFRICA);
$countries = Countries::getByRegion(Countries::$REGION_AMERICAS);
$countries = Countries::getByRegion(Countries::$REGION_ANTARCTIC);
$countries = Countries::getByRegion(Countries::$REGION_ASIA);
$countries = Countries::getByRegion(Countries::$REGION_EUROPE);
$countries = Countries::getByRegion(Countries::$REGION_OCEANIA);

$countries = Countries::getBySubregion('Northern Europe');

Filter by Independence Status

use Orpheus\LaravelCountries\Facades\Countries;

$independent    = Countries::getIndependent(true);
$nonIndependent = Countries::getIndependent(false);

Get All Countries

use Orpheus\LaravelCountries\Facades\Countries;

$all = Countries::getAll();

// As a Laravel Collection
$collection = Countries::getAll([], true);

// Filtered by codes (mixed types supported)
$filtered = Countries::getAll(['CA', 'USA', '276']);

Dropdown List Helper

use Orpheus\LaravelCountries\Facades\Countries;

// Default: keyed by cca3, common name
$list = Countries::getListForDropdown();

// Custom key, official name, translated
$list = Countries::getListForDropdown('cca2', true, 'fra');

// Returns: ['CA' => 'Canada', 'US' => "Les états-unis d'Amérique", ...]

Country Object

use Orpheus\LaravelCountries\Facades\Countries;

$country = Countries::getByCode('CAN');

$country->getAlpha2Code();      // 'CA'
$country->getAlpha3Code();      // 'CAN'
$country->getNumericCode();     // '124'
$country->getOfficialName();    // 'Canada'
$country->getCommonName();      // 'Canada'
$country->getCurrency();        // Currency object (first currency)
$country->getCurrencies();      // Collection of Currency objects
$country->getAttributes();      // Raw attributes array

// Dynamic property access to any attribute
$country->capital;              // ['Ottawa']
$country->region;               // 'Americas'
$country->languages;            // ['eng' => 'English', 'fra' => 'French']
$country->independent;          // true
$country->demonyms;             // ['eng' => ['f' => 'Canadian', 'm' => 'Canadian'], ...]

Currency Object

$currency = $country->getCurrency();

$currency->getCode();           // 'CAD'
$currency->getName();           // 'Canadian dollar'
$currency->getSymbol();         // '$'

Eloquent Cast

Store country references in your database and cast them automatically:

use Orpheus\LaravelCountries\Casts\CountryCast;

class Order extends Model
{
    protected $casts = [
        'country' => CountryCast::class,           // Default: alpha2
        'country' => CountryCast::class . ':alpha3',
        'country' => CountryCast::class . ':numeric',
    ];
}

Macros

The Country class implements Laravel's Macroable trait:

use Orpheus\LaravelCountries\Country;
use Orpheus\LaravelCountries\Facades\Countries;

Country::macro('getFlag', fn () => sprintf(
    'https://flagcdn.com/w320/%s.png',
    strtolower($this->getAlpha2Code())
));

$country = Countries::getByCode('CAN');
$country->getFlag(); // 'https://flagcdn.com/w320/ca.png'

Mixins

use Orpheus\LaravelCountries\Country;
use Orpheus\LaravelCountries\Facades\Countries;

class CustomCountry
{
    public function getFlag(): \Closure
    {
        return fn () => sprintf(
            'https://flagcdn.com/w320/%s.png',
            strtolower($this->getAlpha2Code())
        );
    }
}

Country::mixin(new CustomCountry);

$country = Countries::getByCode('CAN');
$country->getFlag(); // 'https://flagcdn.com/w320/ca.png'

Raw Data Access

use Orpheus\LaravelCountries\Facades\Countries;

$rawData = Countries::getRawData(); // Full array of all country data

Configuration

Publish the config file to customize the data source:

php artisan vendor:publish --provider="Orpheus\LaravelCountries\ServiceProvider"

This creates config/laravel-countries.php where you can point to a custom JSON file:

return [
    'countries_json_path' => null, // null = use built-in data
];

Data Source

Country data is compiled from the REST Countries v3.1 JSON dataset using the included compile script (scripts/compile-data-source.php).

Differences from upstream REST Countries v3.1

Field mapping — nativeName is stored as native under the name key.
Computed field — callingCodes is computed from idd.root + idd.suffixes for convenience.
Translation subset — Only 26 translation languages are included (ara, bre, ces, cym, deu, est, fin, fra, hrv, hun, ind, ita, jpn, kor, nld, per, pol, por, rus, slk, spa, srp, swe, tur, urd, zho).
Currency overrides — The following corrections are applied to upstream data:
- Cuba (CU) — CUC removed (convertible peso eliminated Jan 1, 2021), CUP only.
- Bouvet Island (BV) — NOK added (uninhabited Norwegian territory).
- Heard Island (HM) — AUD added (uninhabited Australian territory).
- Micronesia (FM) — USD added (sometimes missing upstream).
- Antarctica (AQ) — USD, GBP, EUR added (used at research stations).

Recompiling Data

To regenerate the data source from the latest upstream JSON:

composer compile-data-source

API Reference

Method	Returns	Description
`getByCode($code)`	`Country\|null`	Lookup by cca2, cca3, ccn3, or cioc
`getByName($name)`	`array`	Partial match on common/official/native names
`getByFullName($name)`	`array`	Exact match on common or official name
`getByLanguage($language)`	`array`	Search by language code or name
`getByCapital($capital)`	`array`	Search by capital city (partial)
`getByDemonym($demonym)`	`array`	Search by demonym (exact, case-insensitive)
`getByTranslation($translation)`	`array`	Search any translation name (partial)
`getByCurrency($currency)`	`array`	Search by currency code or name
`getByRegion($region)`	`array`	Filter by region
`getBySubregion($subregion)`	`array`	Filter by subregion
`getIndependent($status)`	`array`	Filter by independence status
`getAll($codes, $asCollection)`	`array\|Collection`	Get all or filtered countries
`getListForDropdown($key, $official, $locale)`	`array`	Key-value pairs for dropdowns
`getRawData()`	`array`	Raw country data array

Deprecated Methods (v3.0.0)

Deprecated Method	Replacement
`getByAlpha2Code($code)`	`getByCode($code)`
`getByAlpha3Code($code)`	`getByCode($code)`
`getByNumericCode($code)`	`getByCode($code)`

Credits

Orpheus — Maintainer and fork author.
Patrick Samson — Original laravel-countries package.
REST Countries — v3.1 country data source (compiled and adapted with overrides).
Mohammed Le Doze — Previous data source via mledoze/countries.
All Contributors

License

The MIT License (MIT). Please see License File for more information.

opheus2 / laravel-countries

Maintainers

Details