io238 / laravel-iso-countries
Ready-to-use Laravel models and relations for country (ISO 3166), language (ISO 639-1), and currency (ISO 4217) information with multi-language support.
Installs: 36 757
Dependents: 0
Suggesters: 0
Security: 0
Stars: 37
Watchers: 1
Forks: 9
Open Issues: 7
Requires
- php: ^8.1
- components/flag-icon-css: ^3.5.0
- illuminate/contracts: ^7.0|^8.40|^9.0|^10.0
- illuminate/database: ^7.0|^8.40|^9.0|^10.0
- illuminate/support: ^7.0|^8.40|^9.0|^10.0
- slowprog/composer-copy-file: ^0.3
- spatie/laravel-translatable: ^4.6|^5.0|^6.0
- umpirsky/country-list: ^2.0.6
- umpirsky/currency-list: ^v1.1.1
- umpirsky/language-list: ^v1.1
Requires (Dev)
- orchestra/testbench: ^5.0|^6.0|^7.0
- pestphp/pest: ^1.21
README
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 io238/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/¤cy 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.