Stand With Ukraine 🇺🇦
, (*1)
PHP ISO Codes
, (*2)
:star: This library used to get localized names of countries, currencies, languages and scripts., (*3)
:package: Based on Python's pycountry and Debian's iso-codes., (*4)
:tongue: Current translation status: https://salsa.debian.org/iso-codes-team/iso-codes#status-of-translations, (*5)
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
Installation
You may use this library in different modes:, (*6)
-
sokil/php-isocodes (this library) - install library without database and messages and setup
periodic updates of database and messages by yourself with cron or inside CI/CD pipeline with ./bin/update_iso_codes_db.sh
-
sokil/php-isocodes-db-only - if you do not need internationalisation, use
this library. Database already inside. To update database just periodically update this library.
-
sokil/php-isocodes-db-i18n - if you need internationalisation, use
this library. Database and messages already inside. To update database
just periodically update this library.
💾 Library with included database and localization
To install library with database and i18n:, (*7)
, (*8)
composer require sokil/php-isocodes-db-i18n
💾 Library with included database and without localization
You may also install library with only database (no i18n will be available):, (*9)
, (*10)
composer require sokil/php-isocodes-db-only
💾 Library without database and localization, requires manual database installation and updates
You can install library through Composer:, (*11)
composer require sokil/php-isocodes
Database and gettext files located in related packages inside databases and messages directories.
This packages periodically updated with package version increment., (*12)
If you want to update database, use script ./bin/update_iso_codes_db.sh.
Call this script by cron, during deploy process or when build your docker image., (*13)
./bin/update_iso_codes_db.sh {mode} {base_dir} {build_dir}
| Argument |
Required |
Description |
| mode |
Required |
May be "all" or "db_only". In "all" mode update database (json files) and locallisation (po and mo files), in "db_only" only database will update |
| base_dir |
Required |
Dir where to place database and messages |\ |
| build_dir |
Optional. Default: "/tmp/iso-codes-build" |
Dir where source directory cloned and files original files processed. |
Now you need to configure factory to use this directory:, (*14)
<?php
$databaseBaseDir = '/var/isocodes';
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory($databaseBaseDir);
Translation drivers
Translation drivers required when need to get local names of iso entities., (*15)
Translation driver must implement Sokil\IsoCodes\TranslationDriver\TranslationDriverInterface., (*16)
Instance of driver may be passed to IsoCodesFactory. If it not passed, default GettextExtensionDriver will be used., (*17)
<?php
// gettext driver
$isoCodes = new IsoCodesFactory();
$isoCodes = new IsoCodesFactory(null, new GettextExtensionDriver());
// symfony driver
$driver = new SymfonyTranslationDriver();
$driver->setLocale('uk_UA');
$isoCodes = new IsoCodesFactory(
null,
$driver
);
// dummy driver
$isoCodes = new IsoCodesFactory(
null,
new DummyDriver()
);
Gettext extension driver
This is default translation driver. It requires ext-gettext., (*18)
<?php
// gettext driver
$isoCodes = new IsoCodesFactory();
$isoCodes = new IsoCodesFactory(null, new GettextExtensionDriver());
Locale configuration
Before using IsoCodes database you need to setup valid locale to get translations worked,
because ext-gettext uses system local, configured by setlocale., (*19)
<?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:, (*20)
$ 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):
```sh
$ locale-gen uk_UA.utf8
Generating locales...
uk_UA.utf-8... done
Generation complete., (*21)
### Symfony Translation driver
```php
<?php
$driver = new SymfonyTranslationDriver();
$driver->setLocale('uk_UA');
$isoCodes = new IsoCodesFactory(
null,
$driver
);
Dummy driver
This driver may be used, when localisation of names does not require, and only database of codes is required., (*22)
<?php
$isoCodes = new IsoCodesFactory(
null,
new DummyDriver()
);
Usage
Factory
All databases may be created through factory:, (*23)
<?php
$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., (*24)
So there are scenarios of usage: with optimisations of memory and with optimisation of time., (*25)
Memory optimisation
Database splits into partition files., (*26)
Fetching some entry will load only little part of database.
Loaded entries not stored statically., (*27)
This scenario may be useful when just few entries need
to be loaded, for example on web request when one entry fetched., (*28)
This may require a lot of file read operations., (*29)
Entire database loaded into memory from single JSON file once., (*30)
All entries created and stored into RAM. Next read of save
entry will just return it without io operations with files and building objects., (*31)
This scenario may be useful for daemons to decrease file operations,
or when most entries will be fetched from database., (*32)
This may require a lot of RAM for storing all entries., (*33)
Countries database (ISO 3166-1)
Country contains next names:, (*34)
| Name |
Description |
Example |
| Name |
Required |
Moldova, Republic of |
| Official Name |
Optional |
Republic of Moldova |
| Common Name |
Optional |
Moldova |
| Localised Name |
Optional |
Молдова |
This names may be get from country entity:, (*35)
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$country = $isoCodes->getCountries()->getByAlpha2('UA');
echo $country->getName();
echo $country->getLocalName();
echo $country->getOfficialName();
echo $country->getCommonName();
Also you may get flag of country:, (*36)
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$country = $isoCodes->getCountries()->getByAlpha2('UA');
echo $country->getFlag();
Get localized name of country by it's alpha2 code:, (*37)
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByAlpha2('UA')->getLocalName();
Get localized name of country by it's alpha3 code:, (*38)
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByAlpha3('UKR')->getLocalName();
Get localized name of country by it's numeric code:, (*39)
$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$isoCodes->getCountries()->getByNumericCode('804')->getLocalName();
Get localised list of countries, (*40)
$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
Tests
To start docker tests run following command:, (*41)
./tests/docker/run-test.sh [PHP_VERSION]
For example for PHP 7.1 run following command:, (*42)
./tests/docker/run-test.sh 7.1
See also
Wallogit.com
