<h1 align="center"> Countries </h1>

World Map

What does it gives you?

This package has all sorts of information about countries:

| info | items | ------------------|-------:| | taxes | 32 | | geometry maps | 248 | | topology maps | 248 | | currencies | 256 | | countries | 266 | | timezones | 423 | | borders | 649 | | flags | 1,570 | | states | 4,526 | | cities | 7,376 | | timezones times | 81,153 |

Geology and topology maps

Amongst many other information you'll be able to plot country maps:

Switzerland

Requirements

PHP 8.1+
Uses Laravel Collections (illuminate/collections) - compatible with Laravel 11 & 12

Version Compatibility

| PHP | Countries | Notes | |---------|-----------|-------| | < 8.0 | <= 0.8.2 | Legacy versions | | 8.0 | <= 0.8.3 | Legacy versions | | >= 8.1 | ^1.0 | Modern PHP with Laravel Collections support |

Current version: 1.0.0 - Modern PHP 8.3, 8.4 and 8.5 (alpha) compatibility

What's New in v1.0.0

✅ PHP 8.3, 8.4 and 8.5 (alpha) compatibility
✅ Updated to modern dependency versions
✅ Custom Collection implementation (replaces pragmarx/coollection)
✅ Laravel 10, 11 & 12 support
✅ PHPUnit 10 and 11 support
✅ Maintained full backward compatibility with PHP 8.1

Installing

Use Composer to install it:

composer require pragmarx/countries

Instantiating

use PragmaRX\Countries\Package\Countries;

$countries = new Countries();

echo $countries->where('cca2', 'IT')->first()->hydrateCurrencies()->currencies->EUR->coins->frequent->first();

// or calling it statically

echo Countries::where('cca2', 'IT')->first()->hydrateCurrencies()->currencies->EUR->coins->frequent->first();

Should both return

€1

Overloading the default configuration:

use PragmaRX\Countries\Package\Services\Config;

$countries = new Countries(new Config([
    'hydrate' => [
        'elements' => [
            'currencies' => true,
            'flag' => true,
            'timezones' => true,
        ],
    ],
]));

Usage

This package is not tied to Laravel and doesn't require it to be installed (we have a bridge for this purpose), but it has Laravel Collections in its core, all methods in Collections are available, this way you can do things like filter, map, reduce, search, sort, reject, and a lot more. It, actually, uses Coollection, which is Laravel Collections with a fluent syntax, allowing us to have access to array keys (and values) as object properties.

To get all countries in the data base you just have to:

use PragmaRX\Countries\Package\Countries;

$countries = new Countries();

$all = $countries->all();

To get a json you:

return $countries->toJson();

Filter by keys and values:

$countries->where('name.common', 'Brazil');

Will find Brazil by its common name, which is a

#items: array:22 [▼
  "name" => array:3 [▼
    "common" => "Brazil"
    "official" => "Federative Republic of Brazil"
    "native" => array:1 [▼
      "por" => array:2 [▼
        "official" => "República Federativa do Brasil"
        "common" => "Brasil"
      ]
    ]
  ]

Or alternatively you can filter like this

$countries->whereNameCommon('Brazil');

And, you can go deepeer

$countries->where('name.native.por.common', 'Brasil');

Or search by the country top level domain

$countries->where('tld.0', '.ch');

To get

"name" => array:3 [▼
  "common" => "Switzerland"
  "official" => "Swiss Confederation"
  "native" => array:4 [▶]
]
"tld" => array:1 [▼
  0 => ".ch"
]

And use things like pluck

$countries->where('cca3', 'USA')->first()->hydrateStates()->states->pluck('name', 'postal')->toArray();

To get

"MA" => "Massachusetts"
"MN" => "Minnesota"
"MT" => "Montana"
"ND" => "North Dakota"
...

The package uses a modified Collection which allows you to access properties and methods as objects:

$countries->where('cca3', 'FRA')
         ->first()
         ->borders
         ->first()
         ->name
         ->official;

Should give

Principality of Andorra

Borders hydration is disabled by default, but you can have your borders hydrated easily by calling the hydrate method:

$countries->where('name.common', 'United Kingdom')
         ->hydrate('borders')
         ->first()
         ->borders
         ->reverse()
         ->first()
         ->name
         ->common;

Should return

Ireland

Hydration

To improve performance, hydration, which is enabled by default, can be disable on most country properties, and this is how you manually hydrate properties:

$countries->where('name.common', 'United States')->first()->hydrate('timezones')->timezones->first()->zone_name;

$countries->where('name.common', 'United States')->first()->hydrate('timezones')->timezones->first()->zone_name;

Those are some of the hydratable properties:

Borders
Cities
Currencies
Flag
Geometry
Languages
States
Taxes
Timezone
Topology

Extra where rules

Some properties are stored differently and we therefore need special rules for accessing them, these properties are

ISO639_3 => The 3 letter language code.
ISO4217 => The 3 letter currency code.

You can of course access them like other properties

$countries->whereISO639_3('por')->count();
$countries->where('ISO639_3', 'por')->count();

Mapping

Sometimes you would like to access a property by a different name, this can be done in settings, this way

'maps' => [
    'lca3' => 'ISO639_3'
]

Here we bind the language 3 letter short code ISO format to lca3, which is short for language code alpha 3-letter. So now we can access the property by

$countries->whereLca3('por');

$countries->where('lca3', 'por');

Some other examples from Laravel News and some other contributors

Generate a list of all countries with code, using native name and common

app(PragmaRX\Countries\Package\Countries::class)
->all()
->map(function ($country) {
    $commonName = $country->name->common;

    $languages = $country->languages ?? collect();

    $language = $languages->keys()->first() ?? null;

    $nativeNames = $country->name->native ?? null;

    if (
        filled($language) &&
            filled($nativeNames) &&
            filled($nativeNames[$language]) ?? null
    ) {
        $native = $nativeNames[$language]['common'] ?? null;
    }

    if (blank($native ?? null) && filled($nativeNames)) {
        $native = $nativeNames->first()['common'] ?? null;
    }

    $native = $native ?? $commonName;

    if ($native !== $commonName && filled($native)) {
        $native = "$native ($commonName)";
    }

    return [$country->cca2 => $native];
})
->values()
->toArray();

Should give you 267 (or so) countries like:

"AW" => "Aruba"
"AF" => "افغانستان (Afghanistan)"
"AO" => "Angola"
"AI" => "Anguilla"
"AX" => "Åland (Åland Islands)"
"AL" => "Shqipëria (Albania)"
"AD" => "Andorra"
"AE" => "دولة الإمارات العربية المتحدة (United Arab Emirates)"
"AR" => "Argentina"
"AM" => "Հայաստան (Armenia)"
"AS" => "American Samoa"
"AQ" => "Antarctica"
"TF" => "Terres australes et antarctiques françaises (French Southern and Antarctic Lands)"
"AG" => "Antigua and Barbuda"
"AU" => "Australia"
"AT" => "Österreich (Austria)"
"AZ" => "Azərbaycan (Azerbaijan)"
"BI" => "Burundi"
"BE" => "Belgien (Belgium)"
"BJ" => "Bénin (Benin)"
"BF" => "Burkina Faso"
"BD" => "বাংলাদেশ (Bangladesh)"
"BG" => "България (Bulgaria)"
"BH" => "‏البحرين (Bahrain)"
"BS" => "Bahamas"
"BA" => "Bosna i Hercegovina (Bosnia and Herzegovina)"
"BL" => "Saint-Barthélemy (Saint Barthélemy)"
"SH" => "Saint Helena, Ascension and Tristan da Cunha"
"BY" => "Белару́сь (Belarus)"
"BZ" => "Belize"
"BM" => "Bermuda"
"BO" => "Wuliwya (Bolivia)"
"BQ" => "Caribisch Nederland (Caribbean Netherlands)"
"BR" => "Brasil (Brazil)"
"BB" => "Barbados"
"BN" => "Negara Brunei Darussalam (Brunei)"
"BT" => "འབྲུག་ཡུལ་ (Bhutan)"
"BV" => "Bouvetøya (Bouvet Island)"
"BW" => "Botswana"
"CF" => "Républi

Countries

Install / Use

README