PHPackages                             juanparati/iso-codes - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. juanparati/iso-codes

ActiveLibrary[Utility & Helpers](/categories/utility)

juanparati/iso-codes
====================

A PHP library that provides ISO codes, currencies, languages, timezones and additional geopolitical information

5.3(1y ago)17146.4k↑26%4MITPHPPHP >=8.1CI passing

Since Nov 5Pushed 1y ago1 watchersCompare

[ Source](https://github.com/juanparati/isocodes)[ Packagist](https://packagist.org/packages/juanparati/iso-codes)[ RSS](/packages/juanparati-iso-codes/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (2)Versions (16)Used By (0)

[![Test passed](https://github.com/juanparati/isocodes/actions/workflows/phpunit.yml/badge.svg)](https://github.com/juanparati/isocodes/actions/workflows/phpunit.yml/badge.svg)

🌐 ISOCodes
==========

[](#-isocodes)

What is it?
-----------

[](#what-is-it)

A PHP library that provides a list of structured ISO codes oriented to geography/geopolitical information.

This library provides the following ISOs and codes:

- [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) (Geographical codes)
- [ISO 3166-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) (Geographical codes)
- [Country codes](https://www.iban.com/country-codes) (Geopolitical codes)
- [TLDs](https://en.wikipedia.org/wiki/Country_code_top-level_domain) (Regional TLD)
- [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) (Currency codes)
- [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (Language codes)
- [International dialing codes](https://en.wikipedia.org/wiki/List_of_country_calling_codes)
- [Olson Timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
- [Unicode flags](https://en.wikipedia.org/wiki/Regional_indicator_symbol)
- [European Union Members](https://european-union.europa.eu/principles-countries-history/country-profiles_en)

This library provides localized names for countries, currencies and languages. The library allows to create custom/new locales.

RDMS like MySQL or SQLite is not required in order to use this library. All the data is maintained in separate files that are loaded and linked on demand in a way that keeps a low memory footprint.

### Disclaimer

[](#disclaimer)

This library data is based on international standards recognized by global organizations, the author is not responsible about how the translations and geopolitical data is represented.

If you feel that this library data doesn't comply with the geopolitical views required by your project, fell free to [register a custom dataset](#custom-dataset-and-locales).

Composer
--------

[](#composer)

```
composer require juanparati/iso-codes

```

Laravel
-------

[](#laravel)

This library is compatible with Laravel 8.x+ however it can work as a standalone library.

### Facade registration

[](#facade-registration)

```
'aliases' => [
    ...
    'ISOCodes' => \Juanparati\ISOCodes\Facades\ISOCodesFacade::class,
    ...
]

```

### Configuration

[](#configuration)

Publish configuration file (Required only when custom dataset or locales are required):

```
artisan vendor:publish --provider="Juanparati\ISOCodes\Providers\ISOCodesProvider"

```

Usage
-----

[](#usage)

The list of results are returned as [Collections](https://laravel.com/docs/9.x/collections).

### Country model examples

[](#country-model-examples)

Get the list of all country codes as an array:

```
(new ISOCodes)->countries()->toArray();

```

It returns something like this:

```
[
...
    "ES"=> [
        "alpha2" => "ES",
        "alpha3" => "ESP",
        "numeric" => "724",
        "tld" => ".es",
        "currencies" => [
          "EUR",
        ],
        "languages" => [
          "ES",
          "CA",
          "GL",
          "EU",
        ],
        "continents" => [
          "EU",
        ],
        "capital" => "Madrid",
        "flag" => "🇪🇸",
        "phone_code" => "34",
        "eu_member" => true,
        "name" => "Spain",
        "timezones" => [
            "Europe/Madrid",
            "Africa/Ceuta",
            "Atlantic/Canary",
        ]
    ]
...
];

```

Retrieve all the countries as a Collection:

```
(new ISOCodes)
    ->countries()
    ->all();
```

Retrieve one specific country:

```
(new ISOCodes)
    ->countries()
    ->firstWhere('alpha2', 'ES');
```

or using the shortcut

```
(new ISOCodes)
    ->countries()
    ->findByAlpha2('ES');
```

Retrieve all the countries located in Europe:

```
(new ISOCodes)
    ->countries()
    ->whereContinent('EU');
```

Retrieve all the countries located **only** in Europe:

```
(new ISOCodes)
    ->countries()
    ->whereContinent('EU', true);
```

Retrieve all the countries located in Europe and Asia:

```
(new ISOCodes)
    ->countries()
    ->whereContinent(['EU', 'AS'], true);
```

Retrieve all the countries located in Europe **or** Asia

```
(new ISOCodes)
    ->countries()
    ->whereContinent(['EU', 'AS']);
```

Retrieve all the countries sorted by numeric code descending that uses **only** Euro as currency:

```
(new ISOCodes)
    ->countries()
    ->all()
    ->where('currencies', ['EUR'])
    ->sortByDesc('numeric');
```

or

```
(new ISOCodes)
    ->countries()
    ->whereCurrency('EUR', true)
    ->sortByDesc('numeric');
```

Retrieve all the countries that uses **at least** Euro as currency:

```
(new ISOCodes)
    ->countries()
    ->whereCurrency('EUR');
```

Create a list of countries with their names (useful for generate a listbox options):

```
(new ISOCodes)
    ->countries()
    ->map(fn ($iso) => [
        'label' => $iso->name . ' (' . $iso->alpha2 . ')',
        'value' => $iso->alpha2
    ])
    ->sortBy('label')
    ->values();
```

Retrieve a list of countries that has Portuguese as one of their official languages:

```
(new ISOCodes)
    ->countries()
    ->whereLanguage('PT');
```

- Note that most spoken language of each country should be always the first in the list.

### Language model examples

[](#language-model-examples)

Get the list grouped by language:

```
(new ISOCodes)->languages()->toArray();
```

It returns something like:

```
[
...
    "CA" => [
        "code" => "CA",
        "name" => "Catalan",
        "countries" => [
            [
                "alpha2"     => "AD",
                "alpha3"     => "AND",
                "numeric"    => "020",
                "tld"        => ".ad",
                "currencies" => [ …1],
                "languages"  => [ …1],
                "continents" => [ …1],
                "name"       => "Andorra",
                "timezones"  => [
                    "Europe/Andorra"
                ]
            ],
            ...
        ],
        "currencies" => [
            "EUR",
        ],
        "continents" => [
            "EU",
        ],
    ]
...
];

```

### Continent model examples

[](#continent-model-examples)

Get the list grouped by continent.

Example:

```
(new ISOCodes)->continents()->toArray();
```

### Currency model examples

[](#currency-model-examples)

Get the list grouped by currency.

Example:

```
(new ISOCodes)->currencies()->toArray();
```

### CurrencyNumber model examples

[](#currencynumber-model-examples)

Get the list grouped by currency number.

Example:

```
(new ISOCodes)->currencyNumbers()->toArray();
```

### Property access

[](#property-access)

Each record array member can be accessed using the array and object syntax.

Example:

```
$spain = (new ISOCodes)
    ->countries()
    ->findByAlpha2('ES');

$spain->name;    // Spain
$spain['name'];  // Spain

$spain->toArray();  // Get record as array
$spain->toJson();   // Get record as Json
```

Each record is serializable, that it make it ideal in order to store the results into a cache.

### Use currency numbers instead of currency codes.

[](#use-currency-numbers-instead-of-currency-codes)

The method `setCurrencyAsNumber` specify if the currency code is returned as a number.

Example:

```
(new ISOCodes)
    ->countries()
    ->setCurrencyAsNumber(true)
    ->all();
```

### Node resolution

[](#node-resolution)

The method `setResolution` modify how the associated nodes are structured.

The available nodes are:

- currencies
- languages
- continents

The available node formats are:

- NODE\_AS\_CODE: return the values as codes (It is the default resolution)
- NODE\_AS\_NAME: return the values as the translated values (Example: Instead of 'DA' it returns 'Danish')
- NODE\_AS\_ALL: return the values as codes and translated values (Example: `['DA' => 'Danish']`)
- NODE\_AS\_NONE: the associated values are not included.

Examples:

```
(new ISOCodes)
    ->countries()
    ->setResolution('currencies', \Juanparati\ISOCodes\Enums\NodeResolution::NODE_AS_ALL)
    ->setResolution('languages', \Juanparati\ISOCodes\Enums\NodeResolution::NODE_AS_ALL)
    ->setResolution('continents', \Juanparati\ISOCodes\Enums\NodeResolution::NODE_AS_ALL)
    ->findByAlpha2('PT')
    ->toArray();
```

returns the following:

```
[
    "alpha2"     => "PT",
    "alpha3"     => "PRT",
    "numeric"    => "620",
    "tld"        => ".pt",
    "currencies" => [
        "EUR" => "Euro",
    ],
    "languages"  => [
        "Portuguese",
    ],
    "name"       => "Portugal",
    "capital"    => "Lisboa",
    "flag"       => "🇵🇹",
    "phone_code" => "351",
    "eu_member"  => true,
    "timezones"  => [
        "Europe/Lisbon",
        "Atlantic/Azores",
        "Atlantic/Madeira",
    ],
]

```

instead of:

```
[
    "alpha2"     => "PT",
    "alpha3"     => "PRT",
    "numeric"    => "620",
    "tld"        => ".pt",
    "currencies" => [
        "EUR",
    ],
    "languages"  => [
        "PT",
    ],
    "continents" => [
        "EU",
    ],
    "name"       => "Portugal",
    "capital"    => "Lisboa",
    "flag"       => "🇵🇹",
    "phone_code" => "351",
    "eu_member"  => true,
    "timezones"  => [
        "Europe/Lisbon",
        "Atlantic/Azores",
        "Atlantic/Madeira",
    ],
]

```

The node resolutions works with the others models like "currencies", "languages", etc.

#### Node resolutions and immutability

[](#node-resolutions-and-immutability)

When the resolution is changed it will be back to the previous state in the next model call.

Example:

```
$iso = new ISOCodes();

echo $iso->countries()
    ->setResolution('currencies', \Juanparati\ISOCodes\Enums\NodeResolution::NODE_AS_ALL)
    ->findByAlpha2('PT')
    ->currencies[0];  // Returns "Euro"

echo $iso->countries()
    ->findByAlpha2('PT')
    ->currencies[0];  // Returns "EUR"
```

In order to keep persistent the resolutions it's possible to pass the resolution values to the constructor. Example:

```
$iso = new ISOCodes(new ISOCodes(defaultResolutions: [
            'currencies' =>  \Juanparati\ISOCodes\Enums\NodeResolution::NODE_AS_NAME
        ]);
```

Main language and timezone
--------------------------

[](#main-language-and-timezone)

- The more spoken language is displayed first in the list.
- The country capital timezone is displayed first in the list.

Custom dataset and locales
--------------------------

[](#custom-dataset-and-locales)

It's possible to register custom datasets and locales during the ISOCodes instantiation.

Example:

```
new ISOCodes(['countries' => MyCountryTranslation::class])
```

See the following example with the [country names](./src/Data/Countries/CountriesEN.php).

Macroable models
----------------

[](#macroable-models)

The models are macroable so it's possible to inject custom methods.

Example:

```
\Juanparati\ISOCodes\Models\CountryModel::macro('allEUMembers', function () {
    return $this->where('eu_member', true)->all();
});

(new ISOCodes)->countries()->allEUMembers()->count();   // 27
```

Flags representation in client side
-----------------------------------

[](#flags-representation-in-client-side)

Some operating systems and web browsers may not be able to represent unicode flags due political reasons. I recommend to use the libraries like [country-flag-emoji-polyfill](https://github.com/talkjs/country-flag-emoji-polyfill) in order to provide a graphical representation of the flags in the client side.

Contributions
-------------

[](#contributions)

Feel free to add new locales to this library and send me a pull request.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance46

Moderate activity, may be stable

Popularity43

Moderate usage in the ecosystem

Community11

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 97.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~88 days

Total

15

Last Release

413d ago

Major Versions

0.9.2 → 1.02021-11-21

1.x-dev → 2.12022-10-28

2.2 → 3.02023-05-23

3.0 → 4.12023-05-25

4.x-dev → 5.02024-04-05

PHP version history (3 changes)0.9.2PHP ^8.0

4.1PHP ^8.1

4.x-devPHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/4caf72b4d969cfb8cdfbdc1d594c85b51c9316caf76b80aa0f9de7e3736cf59f?d=identicon)[juanparati](/maintainers/juanparati)

---

Top Contributors

[![juanparati](https://avatars.githubusercontent.com/u/835173?v=4)](https://github.com/juanparati "juanparati (45 commits)")[![jeanlucnguyen](https://avatars.githubusercontent.com/u/10912221?v=4)](https://github.com/jeanlucnguyen "jeanlucnguyen (1 commits)")

---

Tags

laravellanguagescountriesisoflagslocalescurrenciestimezonescodesregions

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/juanparati-iso-codes/health.svg)

```
[![Health](https://phpackages.com/badges/juanparati-iso-codes/health.svg)](https://phpackages.com/packages/juanparati-iso-codes)
```

###  Alternatives

[rinvex/countries

Rinvex Countries is a simple and lightweight package for retrieving country details with flexibility. A whole bunch of data including name, demonym, capital, iso codes, dialling codes, geo data, currencies, flags, emoji, and other attributes for all 250 countries worldwide at your fingertips.

1.7k7.4M48](/packages/rinvex-countries)[pragmarx/countries

PHP Countries and Currencies

1.9k3.3M18](/packages/pragmarx-countries)[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.

5462.3k](/packages/io238-laravel-iso-countries)[nnjeim/world

Laravel countries, states, cities, currencies, languages and IP geolocation

970361.2k3](/packages/nnjeim-world)[pragmarx/countries-laravel

Countries for Laravel

1471.1M2](/packages/pragmarx-countries-laravel)[dougsisk/laravel-country-state

Country & state helper for Laravel.

1681.7M](/packages/dougsisk-laravel-country-state)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)