Skip to content
⭐️ PHP library providing ISO codes with localization: country (ISO 3166-1), subdivision (ISO 3166-2), language (ISO 639-3), currency (ISO 4217) and scripts (ISO 15924)
PHP Shell
Branch: 3.0
Clone or download
Latest commit ff1dc22 Aug 28, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
benchmarks bench May 24, 2019
bin fix release script Jun 1, 2019
databases update database Aug 28, 2019
messages update database Aug 28, 2019
src readme Jun 1, 2019
tests readme Jun 1, 2019
.coveralls.yml extract abstract database Oct 29, 2017
.gitignore Simplify PHP_CodeSniffer configuration Apr 24, 2019
.scrutinizer.yml Create .scrutinizer.yml Nov 7, 2017
.travis.yml remove xdebug config copy May 1, 2019 changelog Aug 28, 2019 Create Jan 15, 2018
LICENSE Update LICENSE Apr 2, 2019 update database Aug 28, 2019
composer.json remove stubs Jun 5, 2019
infection.json.dist infection Nov 7, 2017
phpbench.json bench Nov 13, 2017
phpcs.xml.dist remove stubs Jun 5, 2019
phpunit.xml.dist Simplify PHPUnit configuration Apr 24, 2019


Build Status Latest Stable Version Coverage Status Total Downloads Daily Downloads Scrutinizer Code Quality

⭐️ This library used to get localized names of countries, currencies, languages and scripts.

📦 Based on Python's pycountry and Debian's iso-codes.

🔢 Database version: iso-codes-4.2-202-gfefebff3 from 2019-08-28 23:03

👅 Current translation status:

Table of contents

ISO Standards

  • ISO 3166-1: Country codes (alpha-2, alpha-3, numeric)
  • ISO 3166-2: Principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1
  • ISO 3166-3: Historic countries (alpha-2, alpha-3, alpha-4, numeric)
  • ISO 15924: Scripts
  • ISO 4217: Currencies
  • ISO 639-3: Languages


You can install library through Composer:

composer require sokil/php-isocodes

Locale configuration

Before using IsoCodes database you need to setup valid locale to get translations worked:


// define locale
setlocale(LC_ALL, 'uk_UA.UTF-8');

// init database
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();

// get languages database
$languages = $isoCodes->getLanguages();

// get local name of language
echo $languages->getByAlpha2('uk')->getLocalName(); // will print 'українська'

To get list of available locales, execute under console:

$ locale -a

If you don't see required locales in list, you may install them manually (for Ubuntu):

$ locale-gen uk_UA.utf8
Generating locales...
  uk_UA.utf-8... done
Generation complete.

Manual database update

Database and related gettext files located inside this repo in databases and messages directories. This data periodically updated with package version increment.

If you want to update database more often, use script ./bin/ Call this script by cron, during deploy process or when build your docker image.

/path/to/project/vendor/sokil/php-isocodes/bin/ /var/isocodes

Now you need to configure factory to use this directory:


$databaseBaseDir = '/var/isocodes';

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory($databaseBaseDir);



All databases may be create through factory:

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$languages = $isoCodes->getLanguages();

There are large databases: subdivisions and languages. Loading of entire database into memory may require lot of RAM and time to create all entries in memory.

So there are scenarios of usage: with optimisations of memory and with optimisation of time.

Memory optimisation

Database splits into partition files.

Fetching some entry will load only little part of database. Loaded entries not stored statically.

This scenario may be useful when just few entries need to be loaded, for example on web request when one entry fetched.

This may require a lot of file read operations.

Input-output optimisations

Entire database loaded into memory from single JSON file once.

All entries created and stored into RAM. Next read of save entry will just return it without io operations with files and building objects.

This scenario may be useful for daemons to decrease file operations, or when most entries will be fetched from database.

This may require a lot of RAM for storing all entries.

Countries database (ISO 3166-1)

Get localized name of country by it's alpha2 code:

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();

Get localized name of country by it's alpha2 code:

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();

Get localized name of country by it's numeric code:

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();

Get localised list of countries

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
foreach($isoCodes->getCountries() as $country) {
  echo $country->getLocalName();

Subdivisions database (ISO 3166-2)


$isoCodes = new IsoCodesFactory();

$subDivisions = $isoCodes->getSubdivisions();

// get subdivision by code
$subDivision = $subDivisions->getByCode('UA-43');

// get subdivision code
$subDivision->getCode(); // UA-43

// get subdivision name
$subDivision->getName(); // Respublika Krym

// get localised subdivision name
$subDivision->getLocalName(); // Автономна Республіка Крим

// get subdivision type
$subDivision->getType(); // 'Autonomous republic'

Historic countries database (ISO 3166-3)


$isoCodes = new IsoCodesFactory();

$countries = $isoCodes->getHistoricCountries();

$country = $countries->getByAlpha4('ZRCD');

$country->getName(); //'Zaire, Republic of'
$country->getAlpha4(); // 'ZRCD'
$country->getAlpha3(); // 'ZAR'
$country->getAlpha2(); // 'ZR'
$country->getWithdrawalDate(); // '1997-07-14'
$country->getNumericCode(); // 180

Scripts database (ISO 15924)

$isoCodes = new IsoCodesFactory();

$scripts = $isoCodes->getScripts();

$script = $scripts->getByAlpha4('Aghb');

$script->getName(); // Caucasian Albanian
$script->getLocalName(); // кавказька албанська
$script->getAlpha4(); // Aghb
$script->getNumericCode(); 239

Currencies database (ISO 4217)


$isoCodes = new IsoCodesFactory();

$currencies = $isoCodes->getCurrencies();

$currency = $currencies->getByLetterCode('CZK');

$currency->getName(); // Czech Koruna
$currency->getLocalName(); // Чеська крона
$currency->getLetterCode(); // CZK
$currency->getNumericCode(); // 203

Languages database (ISO 639-3)

$isoCodes = new IsoCodesFactory();

$languages = $isoCodes->getLanguages();

$language = $languages->getByAlpha2('uk');

$language->getAlpha2(); // uk

$language->getName(); // Ukrainian

$language->getLocalName(); // українська

$language->getAlpha3(); // ukr

// Scope of denotation, see mote at
$language->getScope(); // I

// Type of language, see
$language->getType(); // L

$language->getInvertedName(); // null


To start docker tests run following command:

./tests/docker/ [PHP_VERSION]

For example for PHP 7.1 run following command:

./tests/docker/ 7.1

See also

You can’t perform that action at this time.