PHP ISO Codes

⭐ 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-3.79-244-gdae9d2b8 from 2019-03-02 08:40

👅 Current translation status: https://salsa.debian.org/iso-codes-team/iso-codes#status-of-translations

Table of contents

• ISO Standards
• Installation
• Locale configuration
• Manual database update
• Usage
  • Locale configuration
  • Countries database (ISO 3166-1)
  • Subdivisions database (ISO 3166-2)
  • Historic countries database (ISO 3166-3)
  • Scripts database (ISO 15924)
  • Currencies database (ISO 4217)
  • Languages database (ISO 639-3)

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

Installation

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 transtions worked:

<?php

// define locale
putenv('LANGUAGE=uk_UA.UTF-8');
putenv('LC_ALL=uk_UA.UTF-8');
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

uk_UA
uk_UA.koi8u
uk_UA.utf8

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 update_db.sh. Call this script by cron, during deploy process or when build your docker image.

/path/to/project/vendor/sokil/php-isocodes/update_db.sh /var/isocodes

Now you need to configure factory to use this directory:

<?php

$databaseBaseDir = '/var/isocodes';

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

Usage

• Countries database (ISO 3166-1)
• Subdivisions database (ISO 3166-2)
• Historic countries database (ISO 3166-3)
• Scripts database (ISO 15924)
• Currencies database (ISO 4217)
• Languages database (ISO 639-3)

Countries database (ISO 3166-1)

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

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByAlpha2('UA')->getLocalName();

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

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByAlpha2('UKR')->getName();

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

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByAlpha2('804')->getName();

Get localised list of countries

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

Subdivisions database (ISO 3166-2)

<?php

$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)

<?php

$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)

<?php
$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)

<?php

$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)

<?php
$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 https://iso639-3.sil.org/about/scope
$language->getScope(); // I

// Type of language, see https://iso639-3.sil.org/about/types
$language->getType(); // L

$language->getInvertedName(); // null

See also

• State Classifier of objects of administrative and territorial structure of Ukraine - generates database of detailed list of cities and settlements of Ukraine
• A Symfony's PHP replacement layer for the C intl extension that also provides access to the localization data of the ICU library