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

First of all, thanks for this great library :).

Right now, if I want to check if a country code is valid, I need to do this:

try {
    (new ISO3166())->alpha2($value);

    return true;
} catch (InvalidArgumentException $e) {
} catch (OutOfBoundsException $e) {
} catch (DomainException $e) {
}

return false;

or (for PHP ^7.1):

try {
    (new ISO3166())->alpha2($value);

    return true;
} catch (InvalidArgumentException | OutOfBoundsException | DomainException $e) {
    return false;
}

This pull request proposes to add a common exception interface for these three exceptions. Therefore I don't have to check first if my $value argument is a string that matches 2 chars. If there is an ISO3166Exception, and I don't need more details, I know right away that the value I gave leads to nowhere.

New possible behavior (with no BC break):

try {
    (new ISO3166())->alpha2($value);

    return true;
} catch (\League\ISO3166\Exception\ISO3166Exception $e) {
    return false;
}

• adding an optional $countries argument to the constructor
• adding the Countable Interface to determine the number of country in the collection
• adding country array validation and normalization
• adding more internal method to reuse validation and normalization everywhere in the class
• remove the use of strcasecmp since the data is normalized
• test suite is updated to take into account the new feature

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.

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.

I was looking for a lib that get a country code by country name and found this one. Unfortunately, it only works from a country code to a country name. I think it could be great to search by anything. That's why I changed the visibility. One other way may be to add a getByName method but I'm not sure it's better.

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...

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?

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

Create the Dataset interface to encapsulate the operations with the country datasets. This should make extending the dataset easier and also make possible to decorate the data with additional information.

Some examples of applicability:

<?php

// Completely custom datasets
class DatabaseDataset implements Dataset {
    // ...
    public function lookup($key, $value) {
        $stmt = $this->pdo->prepare("select * from countries where :key = :value");
        $stmt->execute([':key' => $key, ':value' => $value]);
    }
}

// Decorating datasets
class LocalizedDataset implements Dataset {
    public function __construct(Dataset $wrapped) {
        $this->wrapped = $wrapped;
    }

    // ...

   public function lookup($key, $value) {
        $data = $this->wrapped->lookup($key, $value);
        $data['translated'] = \Locale::getDisplayRegion('-' . $data['alpha2'], 'pt_BR');
        return $data;
   }
}

Intent of this PR is to slightly improve performance of getBy*() methods, particularly getByNumeric(), by reducing number of strcasecmp() invocations down to one.

Also, internal get() method now has more cleaner interface (renamed to getBy($key, $value)).

Notice: These modifications introduce BC break.

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

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.

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.

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

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',]
*/