A PHP library providing ISO 3166-1 data

Overview

league/iso3166

A PHP library providing ISO 3166-1 data.

Tests Code Coverage License

What is ISO 3166-1

ISO 3166-1 is part of the ISO 3166 standard published by the International Organization for Standardization (ISO), and defines codes for the names of countries, dependent territories, and special areas of geographical interest. The official name of the standard is Codes for the representation of names of countries and their subdivisions – Part 1: Country codes. It defines three sets of country codes:

  • ISO 3166-1 alpha-2 – two-letter country codes which are the most widely used of the three, and used most prominently for the Internet's country code top-level domains (with a few exceptions).
  • ISO 3166-1 alpha-3 – three-letter country codes which allow a better visual association between the codes and the country names than the alpha-2 codes.
  • ISO 3166-1 numeric – three-digit country codes which are identical to those developed and maintained by the United Nations Statistics Division, with the advantage of script (writing system) independence, and hence useful for people or systems using non-Latin scripts.

-- Wikipedia

Installing

$ composer require league/iso3166

Using

See using section of the documentation.

Quick guide:

$data = (new League\ISO3166\ISO3166)->name($name);
$data = (new League\ISO3166\ISO3166)->alpha2($alpha2);
$data = (new League\ISO3166\ISO3166)->alpha3($alpha3);
$data = (new League\ISO3166\ISO3166)->numeric($numeric);

Data sample:

[
    'name' => 'Netherlands',
    'alpha2' => 'NL',
    'alpha3' => 'NLD',
    'numeric' => '528',
    'currency' => [
        'EUR',
    ]
]

Contributing

Feel free to submit a pull request or create an issue.

License

league/iso3166 is licensed under the MIT license.

Source(s)

Comments
  • Implementing a DataProvider Service Manager

    Implementing a DataProvider Service Manager

    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
    enhancement 
    opened by nyamsprod 10
  • Adding a common exception interface

    Adding a common exception interface

    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;
    }
    
    opened by Einenlum 7
  • Enabling replacing the country list

    Enabling replacing the country list

    • 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
    opened by nyamsprod 7
  • Please add support for Kosovo (XK)

    Please add support for Kosovo (XK)

    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.

    opened by willemstuursma 6
  • Aliases

    Aliases

    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.

    opened by robertdeboer 5
  • public visibility for getBy

    public visibility for getBy

    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.

    opened by rap2hpoutre 5
  • Antarctica data incomplete/questionable

    Antarctica data incomplete/questionable

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

    opened by heiglandreas 5
  • New release to prevent deprecations triggered on PHP 8.1

    New release to prevent deprecations triggered on PHP 8.1

    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?

    opened by christian-kolb 4
  • country code for kosovo is added

    country code for kosovo is added

    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

    opened by galion96 4
  • Create abstraction for the datasets

    Create abstraction for the datasets

    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;
       }
    }
    
    opened by fcoedno 4
  • getBy*() performance improvements

    getBy*() performance improvements

    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.

    opened by nikolaposa 4
  • Language to be used for default locales

    Language to be used for default locales

    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

    opened by rlweb 0
  • "Czech Republic" or "Czechia" (Alias -feature request)

    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.

    opened by cottton 3
  • shouldn't the main API be static?

    shouldn't the main API be static?

    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.

    opened by MeerKatDev 1
  • Region, sub-region and region codes

    Region, sub-region and region codes

    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

    enhancement help wanted 
    opened by OzzyCzech 2
  • A more advanced version with Translation support?

    A more advanced version with Translation support?

    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',]
    */
    
    enhancement 
    opened by andrewfenn 2
Releases(4.1.0)
Owner
The League of Extraordinary Packages
A group of developers who have banded together to build solid, well tested PHP packages using modern coding standards.
The League of Extraordinary Packages
PHP library providing retry functionality with multiple backoff strategies and jitter support

PHP Backoff Easily wrap your code with retry functionality. This library provides: 4 backoff strategies (plus the ability to use your own) Optional ji

Signature Tech Studio 145 Dec 21, 2022
MOP is a php query handling and manipulation library providing easy and reliable way to manipulate query and get result in a fastest way

Mysql Optimizer mysql optimizer also known as MOP is a php query handling and manipulation library providing easy and reliable way to manipulate query

null 2 Nov 20, 2021
Small library providing some functional programming tools for PHP, based on Rambda

Functional library for PHP. Features: set of useful functions helpful in functional programming all functions are automatically curried every array ca

Wojciech Nawalaniec 5 Jun 16, 2022
Tiny PHP library providing retry functionality with multiple backoff strategies and jitter support

JBZoo / Retry 4 retry strategies (plus the ability to use your own) Optional jitter / randomness to spread out retries and minimize collisions Wait ti

JBZoo Toolbox 6 Dec 19, 2022
Melek Berita Backend is a service for crawling data from various websites and processing the data to be used for news data needs.

About Laravel Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experie

Chacha Nurholis 2 Oct 9, 2022
StringBuffer is a PHP class providing operations for efficient string buffering

StringBuffer is a PHP class providing operations for efficient string buffering

null 1 May 26, 2022
A simple API with Guzzle wrapper, providing easy access to wppconnect's endpoints.

WPPConnect Team Wppconnect Laravel Client A simple API with Guzzle wrapper, providing easy access to wppconnect's endpoints. Requirements PHP 7.4 or n

null 28 Dec 18, 2022
Skosmos is a web-based tool providing services for accessing controlled vocabularies, which are used by indexers describing documents and searchers looking for suitable keywords.

Skosmos is a web-based tool providing services for accessing controlled vocabularies, which are used by indexers describing documents and searchers looking for suitable keywords.

National Library of Finland 195 Dec 24, 2022
Bundle providing Honeypot field for the Form Builder in Ibexa DXP Experience/Commerce (3.X)

IbexaHoneypot Bundle providing Honeypot field for the Form Builder in Ibexa DXP Experience/Commerce (3.X) What is Honey pot? A honey pot trap involves

null 1 Oct 14, 2021
Starless Sky is a network protocol for secure identities, providing the use of assymetric identities, public information, end-to-end messaging and smart contracts

Descentralized network protocol providing smart identity over an secure layer. What is the Starless Sky Protocol? Starless Sky is a network protocol f

Starless Sky Protocol 3 Jun 19, 2022
It is an open-source and free project, which is faced with the drawing lovers, providing a free and simple Gallery service

It is an open-source and free project, which is faced with the drawing lovers, providing a free and simple Gallery service

WeepingDogel 5 Dec 15, 2022
Dobren Dragojević 6 Jun 11, 2023
Data visualization for NASA's DSNNow public data

DSN Monitor Data visualization for NASA's DSNNow public data. A live version of the project can be accessed at http://dsnmonitor.ddns.net. Description

Vinz 2 Sep 18, 2022
Import data from and export data to a range of different file formats and media

Ddeboer Data Import library This library has been renamed to PortPHP and will be deprecated. Please use PortPHP instead. Introduction This PHP library

David de Boer 570 Dec 27, 2022
Samsui is a factory library for building PHP objects useful for setting up test data in your applications.

#Samsui Samsui is a factory library for building PHP objects useful for setting up test data in your applications. It is mainly inspired by Rosie for

Sam Yong 31 Nov 11, 2020
First Data driver for the Omnipay PHP payment processing library

Omnipay: First Data First Data driver for the Omnipay PHP payment processing library Omnipay is a framework agnostic, multi-gateway payment processing

The League of Extraordinary Packages 20 Oct 23, 2022
Library download currency rate and save in database, It's designed to be extended by any available data source.

Library download currency rate and save in database, It's designed to be extended by any available data source.

Flexmind. Krzysztof Bielecki 2 Oct 6, 2021
A small marshalling library used to encode/decode data from classes

A small marshalling library used to encode/decode data from classes

Matthew Jordan 9 Sep 22, 2022
📦 "PHP type names" contains the list of constants for the available PHP data types.

PHP type names PHP type names ?? Description Simple library containing the list of constants for the available PHP data types. Use those constant type

♚ PH⑦ de Soria™♛ 4 Dec 15, 2022