README

Simple ISO 3166-1 is a small library to convert country codes ISO 3166-1 (two and three letters country codes) and native, English and French names. It is built from the official standard lists ISO 3166-1.

Every country is identified by a canonical three letters code, and has a two letters code and a three digits numeric code. Any of them, or any name, can be used as input. So there are three ways to get a code:

code3letters() always returns the canonical three letters code. All the lists of names and the numeric codes are keyed by it.
code() returns the shortest code, so the two letters one, since every country has one. It is the region subtag used to build an IETF language tag (BCP 47), so the value of a html attribute lang: fr and BE give fr-BE.
numerical() returns the three digits code.

Warning: until version 0.2, code() always returned the three letters code, and code3letters() was an alias of it. As every country has a two letters code, code() never returns three letters anymore: replace it by code3letters() to keep the previous result.

This library is used in the module Bulk Import for Omeka S and some other places.

The list of codes may be updated by ISO, so some codes may be removed and some other ones may be added regularly.

Installation

This module is a composer library available on [packagist]:

composer require daniel-km/simple-iso-3166-1

Usage

Once included in your code via composer or with require_once 'path/to/vendor/daniel-km/simple-iso-3166-1/src/Iso3166p1.php;', you can use it like that:

$countries = [
    'fr',
    'fra',
    '250',
    '76',
    'France',
    'Germany',
    'Deutschland',
    'fxxx',
];
$result = [];
foreach ($countries as $country) {
    $result[$country] = [
        'country'               => $country,
        'code'                  => \Iso3166p1\Iso3166p1::code($country),
        'code3letters'          => \Iso3166p1\Iso3166p1::code3letters($country),
        'short'                 => \Iso3166p1\Iso3166p1::code2letters($country),
        'numeric'               => \Iso3166p1\Iso3166p1::numerical($country),
        'all'                   => \Iso3166p1\Iso3166p1::codes($country),
        'native'                => \Iso3166p1\Iso3166p1::name($country),
        'English name'          => \Iso3166p1\Iso3166p1::englishName($country),
        'French name'           => \Iso3166p1\Iso3166p1::frenchName($country),
    ];
}
print_r($result);

Result:

country	code	code3letters	short	numeric	all	native	English name	French name
fr	FR	FRA	FR	250	FR, FRA, 250	France	France	France
fra	FR	FRA	FR	250	FR, FRA, 250	France	France	France
250	FR	FRA	FR	250	FR, FRA, 250	France	France	France
76	BR	BRA	BR	076	BR, BRA, 076	Brasil	Brazil	Brésil
France	FR	FRA	FR	250	FR, FRA, 250	France	France	France
Germany	DE	DEU	DE	276	DE, DEU, 276	Deutschland	Germany	Allemagne
Deutschland	DE	DEU	DE	276	DE, DEU, 276	Deutschland	Germany	Allemagne
fxxx

Notes:

Unlike Simple ISO 639-3, where only 184 of the 7929 languages have a two letters code, every country of the standard has one, so code() always returns two letters and code2letters() is never empty.
A numeric code that is not padded with zeros is accepted, so 76 is the same as 076, but numerical() always returns three digits.
The case of the names is not significant.
Every method returns an empty string when the country does not exist, and codes() returns an empty array.

Development

The lists are automatically generated from this command:

php -f scripts/generate.php

Unlike Simple ISO 639-3, the codes are not fetched online: they are read from scripts/iso-3166-1.json, that was extracted from a response of the ISO Online Browsing Platform.

Run the tests with:

composer install
vendor/bin/phpunit

Warning

Use it at your own risk.

It’s always recommended to backup your files and your databases and to check your archives regularly so you can roll back if needed.

Troubleshooting

See online issues page on GitLab.

License

Module

This module is published under the CeCILL v2.1 license, compatible with GNU/GPL and approved by FSF and OSI.

This software is governed by the CeCILL license under French law and abiding by the rules of distribution of free software. You can use, modify and/ or redistribute the software under the terms of the CeCILL license as circulated by CEA, CNRS and INRIA at the following URL "http://www.cecill.info".

As a counterpart to the access to the source code and rights to copy, modify and redistribute granted by the license, users are provided only with a limited warranty and the software’s author, the holder of the economic rights, and the successive licensors have only limited liability.

In this respect, the user’s attention is drawn to the risks associated with loading, using, modifying and/or developing or reproducing the software by the user in light of its specific status of free software, that may mean that it is complicated to manipulate, and that also therefore means that it is reserved for developers and experienced professionals having in-depth computer knowledge. Users are therefore encouraged to load and test the software’s suitability as regards their requirements in conditions enabling the security of their systems and/or data to be ensured and, more generally, to use and operate it in the same conditions as regards security.

The fact that you are presently reading this means that you have had knowledge of the CeCILL license and that you accept its terms.

daniel-km / simple-iso-3166-1

Maintainers

Package info

Statistics

Security