Just run into that.
Wiki: since 2016 Czechia is official.

Thought i just ask if there would be a chance to add an alias -
So if i get (user) input Czech Republic it points to Czechia internally.

If I may suggest, I would consider the use of Aliases for the most common countries.

A few examples:

• United States vs United States Of America
• Britain vs Great Britain

I ran into an issue where I was not getting a ISO 2 letter code for US orders. Upon investigation I found out the reason was because the ordering system we use writes it as "United States" and not "United States Of America" which is what the library expects. While I can understand not wanting to add bloat by allowing any/all country alias I do feel the most common ones would be a great way to add some graceful wiggle room. I know of very few systems that use the full name for the US.

Should it not be "Vietnam"?

Hello i want the url of my app to rto display like this myapp.com/us/home etc ,pls logic

At the moment when your searching it has to look thru all the countries in the array which is essentially O(n) performance.

Would it be an idea to keep a cached/compiled list for each type of lookup? That would mean you instantly return the data without any scanning taking it down to O(1) performance.

Example implementation:

private $lookupAlpha2 = ['AF' => '004', ...., 'US' => '840'];
private $countries = [
 '004' => [
    'name' => 'Afghanistan',
    'alpha2' => 'AF',
    'alpha3' => 'AFG',
    'numeric' => '004',
    'currency' => [
        'AFN',
    ],
],
'840' => [
    'name' => 'United States of America',
    'alpha2' => 'US',
    'alpha3' => 'USA',
    'numeric' => '840',
    'currency' => [
        'USD',
    ],
  ],
];

public function alpha2($alpha2) {
	if (isset($this->lookupAlpha2[$alpha2])) {
		return $this->countries[$lookupAlpha2[$alpha2]];
	}
}

The countries which are now keyed by the unique number code allows instant lookup.

Alternatively, if the lookups will be compiled automatically, we could just store the index of the country and use that rather than the numeric code.

Would be useful to have a "short_name" attribute for some of the more verbose entries such as "United Kingdom of Great Britain and Northern Ireland".

My thoughts are that the biggest thing i can see this being used for is generating country select lists (or currency select lists). However some of the longer country names aren't really ideal in this scenario (and from a UX perspective, users are used to the shorter names).

I know you'll probably not want to add anything that isn't defined by the ISO, but it appears that whilst ISO 3166-1 uses the longer names, ISO 3166-2 appears to use the more common shorter variants (although i'm no expert, and wikipedia is admittedly not always the most truthful of sources).

https://www.iso.org/obp/ui/#iso:code:3166:AN
iso2: AN
iso3 ANT

Unfortunately, because ISO3166 have private visibility modifier on its internal "dataset" ($countries) –

we can do nothing to provide more library custom functionality in the project.

For example, we need to consider the CI (Canary Islands) country code as Spain, so one of the possible solutions for that is to include CI in the dataset, but I can't extend it without copy-paste the whole ISO3166 class.

Raising the visibility level to protected will allow me to extend your class and modify the dataset for my needs. Moreover, it does not even look like BC.

In most use cases the call is used once, why isn't the library making static calls? Like ISO3166::alpha2(..).
Creating an object every time seems quite cumbersome.

Under recent changes, Croatia is now using the Euro;

https://www.sail-croatia.com/resources/currency-in-croatia

As of January 2023, the currency used in Croatia is the Euro. Prior to this change, Croatia’s official currency was the Croatian Kuna (HRK) between 1994 and 2023

Thanks. Amazing work here from everyone!

Hi there! What about that #86 ?

I'm considering (either, or both) the following 2 options:

• extend readme with some basic examples;
• create api documentation and use the gh-pages branch.

I'm getting this deprecation warning using PHP 8.1

Return type of League\ISO3166\ISO3166::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice in /xyz/vendor/league/iso3166/src/ISO3166.php

Could you fix this please? :) Thanks!

This is a big feature request, however it would be nice to be able to have some extra classes I could plug in to swap the country name into different languages.

Here is some mockup code to demonstrate how you might use such an implementation..

use \League\ISO3166\ISO3166;
use \League\ISO3166\Translate;

$translate = new Translate;
$iso3166   = new ISO3166;
/* example data (original in english)
    ['name' => 'China',
    'alpha2' => 'CN',
    'alpha3' => 'CHN',
    'numeric' => '156',
    'currency' => 'CNY',]
*/

$iso3166_zh_hans = $translate->use('zh-Hans', $iso3166);
/* example data (Chinese Simplified)
    ['name' => '**',
    'alpha2' => 'CN',
    'alpha3' => 'CHN',
    'numeric' => '156',
    'currency' => 'CNY',]
*/

$iso3166_zh_hant = $translate->use('zh-Hant', $iso3166);
/* example data (Chinese Traditional)
    ['name' => '中國',
    'alpha2' => 'CN',
    'alpha3' => 'CHN',
    'numeric' => '156',
    'currency' => 'CNY',]
*/

Having the language available for the country would be perfect similar to how currency is set using ISO-639 Language Codes. This is great for creating a default locale for the country.

Example: en-GB - English for the United Kingdom

ext-pcntl library is not installed by default in many PHP environments and support for this feature requires a recompile of PHP.

That being said, perhaps phpunit/php-invoker shouldn't be used as a dependency.

btw Not even sure whether its features are used in unit tests of this library at the moment.

Hi,

In ISO 3166-1 many countries in the official standard use the definite article (the) in their name.

An example is Korea (the Republic of) (alpha2 code KR)

The ISO standard list shows it as "Korea (the Republic of)": https://www.iso.org/obp/ui/#iso:code:3166:KR

This package shows it as "Korea (Republic of):" https://github.com/thephpleague/iso3166/blob/main/src/ISO3166.php#L1278

Does the standard allow for the definite article to be optional or is this an error / omssion?

Instead of using generic SPL exceptions, I think it would be better to use local namespace exceptions, specifically tailored for each use-case. This will make testing also easier/more robust. This change would not be backwards compatible however.

I've gotten an OutOfBoundsException for the following alpha-2 codes:

• AC
• IC
• EA
• DG
• EZ
• XK
• TA
• UN

So you might want to update your data.

it appears that library does not have support for iso3code for Kosovo, and since the class is marked final it can not be extended to add the data manually

Trying to install the package via Composer:

composer require league/iso3166

Freezes downloading:

Installs: league/iso3166:dev-main cebaa47
  - Downloading league/iso3166 (dev-main cebaa47)

Anyone else experiencing this?

XK is missing, which is the code of Kosovo. Would it be possible to add it?

Some users come to us from the Canary Islands, but we can't validate them because this library does not have Canary Islands ISo code representation (IC).

It would be good to add it.

I prepared a repo where you can use the CLI to fetch the newest ISO 3166 list or use the countries.json file. https://github.com/detrin/download-iso3166-list

Create an initial release, should contain:

• source
• tests
• readme
• license
• various dotfiles

Deprecated since 1.x, should be removed before tagging the first 2.x release.

great job on releasing the package.
I was thinking if it was possible to implement a service manager to

• decouple the countries data from the ISO3166.php
• enable refreshing the data with a script without having to upgrade to a new fix version ?
  Like how Jeremy Kendall did with his php domain parser.
  Because of politics country data change a lot and with the current architecture it would mean a security fix upgrade each time a country is added/changed/removed from the list

the currency key should be standardized to being an array. sometimes the country has 1 currency, but sometimes more. I believe it would be easier to standardize or add a currencies key where the data is in an array of ISO4217 code. This way when calling this index you don't have to make a check before using the data.

$country['currencies'] = !is_array($country['currency']) ? [$country['currency']] : $country['currency'];
/// now you have a normalized currency index to work with in you code.

Currently, there is no entry for Canary Islands:
https://www.iso.org/obp/ui/#iso:code:3166:IC

The PR #79 adds the missing entry.

Thanks!
Best regards,
Pascal

Ignore this, submitted an issue then immediately found the solution.

I see that the stable version 1.0.x has a different API than the master branch:

// 1.0.x
$data = (new League\ISO3166\ISO3166)->getByAlpha2($alpha2);
// master
$data = (new League\ISO3166\ISO3166)->alpha2($alpha2);

The documentation describes the master API with no hint that it is different in stable.

Also the documentation should contain an example of what the $data variable contains.

The most valuable methods in ISO3166 class rely on multibyte string comparisons:

So I think the library should describe ext-mbstring as a required extension in the composer.json schema.

Is there a reason this project is named iso3166?

Surely CountryCodes (or something more inventive) would make this a lot more usable. I personally rename it in all my use statements, but I'd rather not do that.

I'm pretty sure Antarctica has not only Norwegian Krones as a currency.

According to https://en.wikipedia.org/wiki/Antarctica there are different country-calling-codes and currencies depending on the area/station/base on the continent.

So the entry in https://github.com/thephpleague/iso3166/blob/master/src/ISO3166.php#L215 should perhaps be altered...

From Wikipedia:

The code XK is being used by the European Commission, the IMF, and SWIFT, CLDR and other organizations as a temporary country code for Kosovo.

I get the following deprecations using version 3.0.0.

[2022-07-13T09:21:55.671686+00:00] php.INFO: Deprecated: Return type of League\ISO3166\ISO3166::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice {"exception":"[object] (ErrorException(code: 0): Deprecated: Return type of League\\ISO3166\\ISO3166::count() should either be compatible with Countable::count(): int, or the #[\\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice at /var/www/html/vendor/league/iso3166/src/ISO3166.php:111)"} []
[2022-07-13T09:21:55.672165+00:00] php.INFO: Deprecated: Return type of League\ISO3166\ISO3166::getIterator() should either be compatible with IteratorAggregate::getIterator(): Traversable, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice {"exception":"[object] (ErrorException(code: 0): Deprecated: Return type of League\\ISO3166\\ISO3166::getIterator() should either be compatible with IteratorAggregate::getIterator(): Traversable, or the #[\\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice at /var/www/html/vendor/league/iso3166/src/ISO3166.php:123)"} []

According to the commit history, this was already fixed on 19.10.2021 but there hasn't been a release since 05.12.2020. Is it possible to trigger a new bugfix release like 3.0.1 that includes this?

Hi,

Is it possible to include other countries such as countries of the UK - England, Scotland, Wales, and Northern Ireland?

I can see those countries in wiki (see the link below) but it doesn't have some ISO 3166-1 and 3166-2 data.
https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes

Thoughts?

Hi,
thanks for such great package.

It seems to BYN currency should be added to Belarus https://en.wikipedia.org/wiki/Belarusian_ruble
Is the currencies referrers to some ISO?
I'll check for BYN then

moved outside of src.

It helps composer dumpautoload -o flag I believe. As you are good in it I don't need to tell more on it .

Currently all the countries are loaded in memory whenever you want to do a lookup.

The typical usage of this library (I would argue) is to lookup information about "common" countries.

To avoid loading a massive array in memory, would it be an idea to separate the country information into different files grouped by approximate population size?

So maybe we have 3 groups of population sizes: high, med, low.

First the library will attempt to lookup information from the high population countries, then if nothing found, load + try the med file, etc.

Personally I think grouping the data by population size makes a lot of sense in how the library will be commonly used.

Alternatively, we could have an option to generate a compiled/cached version of "common" countries per-app. So maybe there's a way in this library where we can generate (by command) an optimised lookup table based on the apps commonly-looked up country information.

There is missing an ANT (Netherlands Antille) ISO code. Regarding this article:
https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Transitional_reservations
It's beeing reserved.

Is there any documentation?

There is a bug in the lookup method https://github.com/thephpleague/iso3166/blob/main/src/ISO3166.php#L163-L165
Look at https://3v4l.org/evSRJ this shows that the second part of the if condition is true for empty string input, this is effectively always true causing the lookup to always return Afghanistan when searching by empty string.
I haven't checked if this works for all fields, but I guess it could, because why not?!

Hi there,

will be possible add region, sub-region and region codes?

There are some great resources about that: https://github.com/lukes/ISO-3166-Countries-with-Regional-Codes

Roman