README

⚠️ This is a fork while the official repo doesn't support Laravel 11/12 ⚠️

This package provides ready-to-use application models and seeds the database with ISO data from various sources. This package can be used in multi-language apps and supports Country/Language/Currency names in almost any locale.

Included datasets

• Countries: ISO 3166 alpha 2 (incl. names, capital, lat/lon coordinates, TLD, phone calling code, regions, population, gini, area)
• Languages: ISO 639-1 (incl. names, language-family, wiki link)
• Currencies: ISO 4217 (incl. names, symbol, decimal digits, rounding)

Unlike other packages, this one also includes relevant data relationships, such as:

// Official languages spoken in Luxembourg ('LU') Country::find('LU')->languages; // Currencies used in Ghana ('GH') Country::find('GH')->currencies; // Countries that have Spanish ('es') as one of their official languages  Language::find('es')->countries; // Countries that use the Euro ('EUR') as currency Currency::find('EUR')->countries;

Installation

You can install the package via composer:

composer require arthurydalgo/laravel-iso-countries

The latest version of this package requires PHP version 8.0 or above. If you need support for PHP 7.4, please install version 2 of this package.

Migrations

There is no need to run any migrations. All country data information is stored in a pre-compiled SQLITE database that is stored within this package.

By default, this database includes all country/language/&currency names translated into English, German, French, and Spanish. If you want to compile your own database with other languages, please see the instructions here.

Rebuilding the database

Country-level ISO data does not change very often. Nevertheless, if at any time you want to update the ISO data to the latest available version, you can manually re-seed the tables:

Config

Optionally, you can publish the config file with:

php artisan vendor:publish --provider="Io238\ISOCountries\ISOCountriesServiceProvider" --tag="config"

In the config you can define, which translations of country/language/currency names you want to store in your DB.

This is the contents of the published config file:

[ // Supported locales for names (countries, languages, currencies) 'locales' => [ 'en', 'de', 'fr', 'es', ], // Path for storing your own SQLITE database 'database_path' => database_path('iso-countries.sqlite'), ];

After making changes to the config you need to re-build the database with the following command:

php artisan db:seed countries:build

This will create a new SQLITE database and stores it in your project at database/iso-countries.sqlite. Exclude this file from .gitignore to have it available in all environments.

# database/.gitignore *.sqlite* !iso-countries.sqlite

Usage

Country model

Country::find('AD'); Io238\ISOCountries\Models\Country { id: "AD", alpha3: "AND", name: "{"en":"Andorra","de":"Andorra","fr":"Andorre","es":"Andorra"}",  native_name: "Andorra", capital: "Andorra la Vella", top_level_domain: ".ad", calling_code: "376", region: "Europe", subregion: "Southern Europe", population: 78014, lat: 42.5, lon: 1.5, demonym: "Andorran", area: 468, }

Language model

Country::find('pt'); Io238\ISOCountries\Models\Language { id: "pt", iso639_2: "por", iso639_2b: null, name: "{"en":"Portuguese","de":"Portugiesisch","fr":"portugais","es":"portugu\u00e9s"}",  native_name: "Português", family: "Indo-European", wiki_url: "https://en.wikipedia.org/wiki/Portuguese_language", }

Currency model

Currency::find('COP'); Io238\ISOCountries\Models\Currency { id: "COP", name: "{"en":"Colombian Peso","de":"Kolumbianischer Peso","fr":"peso colombien","es":"peso colombiano"}",  name_plural: "Colombian pesos", symbol: "CO$", symbol_native: "$", decimal_digits: 0, rounding: 0, }

Query relationships

All models have pre-defined many-to-many relationships that can be queried:

// Retrieve languages that are spoken in Luxembourg Country::find('LU')->languages; Illuminate\Database\Eloquent\Collection { all: [ Io238\ISOCountries\Models\Language { id: "de", iso639_2: "deu", iso639_2b: "ger", name: "{"en":"German","de":"Deutsch","fr":"allemand","es":"alem\u00e1n"}", native_name: "Deutsch", family: "Indo-European", wiki_url: "https://en.wikipedia.org/wiki/German_language", }, Io238\ISOCountries\Models\Language { id: "fr", iso639_2: "fra", iso639_2b: "fre", name: "{"en":"French","de":"Franz\u00f6sisch","fr":"fran\u00e7ais","es":"franc\u00e9s"}", native_name: "français, langue française", family: "Indo-European", wiki_url: "https://en.wikipedia.org/wiki/French_language", }, Io238\ISOCountries\Models\Language { id: "lb", iso639_2: "ltz", iso639_2b: null, name: "{"en":"Luxembourgish","de":"Luxemburgisch","fr":"luxembourgeois","es":"luxemburgu\u00e9s"}", native_name: "Lëtzebuergesch", family: "Indo-European", wiki_url: "https://en.wikipedia.org/wiki/Luxembourgish_language", }, ], } 

// Retrieve all countries that use the Euro (EUR) as currency. Currency::find('EUR')->countries->pluck('name'); Illuminate\Support\Collection { all: [ "Andorra", "Austria", "Åland Islands", "Belgium", "St. Barthélemy", "Cyprus", "Germany", "Estonia", "Spain", "Finland", "France", "French Guiana", "Guadeloupe", "Greece", "Ireland", "Italy", "Lithuania", "Luxembourg", "Latvia", "Monaco", "Montenegro", "St. Martin", "Martinique", "Malta", "Netherlands", "St. Pierre & Miquelon", "Portugal", "Réunion", "Slovenia", "Slovakia", "San Marino", "French Southern Territories", "Vatican City", "Republic of Kosovo", "Mayotte", "Zimbabwe", ], }

Localized names

Each of the package models (Country, Language, Currency) has a ->name attribute, which will be displayed in the app's locale, using the spatie/laravel-translatable package. The default config will migrate localized names for en, de, fr, and es. This can be adjusted in the config. The config app.locale and app.fallback_locale are automatically included.

// Set the app locale app()->setLocale('fr'); // Retrieve the top 10 countries in Africa (by population): Io238\ISOCountries\Models\Country::where('region', 'Africa')->orderByDesc('population')->limit(10)->pluck('name'); // Country names will be returned according to the app locale (fr = French) Illuminate\Support\Collection { all: [ "Nigéria", "Éthiopie", "Égypte", "Congo-Kinshasa", "Afrique du Sud", "Tanzanie", "Kenya", "Algérie", "Soudan", "Ouganda", ], }

Attribute casting

If you already use ISO codes in your models, you can enrich them by casting them as Country/Language/Currency model:

use Io238\ISOCountries\Casts\Currency; class MyModel{ // ... protected $casts = [ 'currency' => Currency::class, ]; // ... } // Now you can dynamically retrieve all meta data associated with the currency MyModel::first()->currency; Io238\ISOCountries\Models\Currency { id: "JPY", name: "{"en":"Japanese Yen","de":"Japanischer Yen","fr":"yen japonais","es":"yen"}",  name_plural: "Japanese yen", symbol: "¥", symbol_native: "￥", decimal_digits: 0, rounding: 0, } // When filling the model, the ISO code (string) or the model can be used  MyModel::first()->update(['currency' => 'USD']); MyModel::first()->update(['currency' => Io238\ISOCountries\Models\Currency::find('USD')]);

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Martin
• https://restcountries.com
• https://github.com/umpirsky/country-list
• https://github.com/umpirsky/language-list
• https://github.com/umpirsky/currency-list
• https://github.com/spatie/laravel-translatable
• All Contributors

License

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