sokil/php-isocodesPublic

NotificationsYou must be signed in to change notification settings
Fork13
Star178

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

License

MIT license

178 stars 13 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 398 Commits
.github		.github
benchmarks		benchmarks
bin		bin
src		src
tests		tests
.coveralls.yml		.coveralls.yml
.gitattributes		.gitattributes
.gitignore		.gitignore
.scrutinizer.yml		.scrutinizer.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
infection.json.dist		infection.json.dist
phpbench.json		phpbench.json
phpcs.xml.dist		phpcs.xml.dist
phpunit.xml.dist		phpunit.xml.dist
psalm.xml		psalm.xml

Repository files navigation

Stand With Ukraine 🇺🇦

PHP ISO Codes

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

📦 Based on Python'spycountry and Debian'siso-codes.

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

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:

sokil/php-isocodes (this library) - install library without database and messages and setupperiodic 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, usethis library. Database already inside. To update database just periodically update this library.
sokil/php-isocodes-db-i18n - if you need internationalisation, usethis library. Database and messages already inside. To update databasejust periodically update this library.

💾 Library with included database and localization

To installlibrary with database and i18n:

composer require sokil/php-isocodes-db-i18n

💾 Library with included database and without localization

You may also installlibrary with only database (no i18n will be available):

composer require sokil/php-isocodes-db-only

💾 Library without database and localization, requires manual database installation and updates

You can install library through Composer:

composer require sokil/php-isocodes

Database and gettext files located in related packages insidedatabases andmessages directories.This packages periodically updated with package version increment.

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.

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

<?php$databaseBaseDir ='/var/isocodes';$isoCodes =new \Sokil\IsoCodes\IsoCodesFactory($databaseBaseDir);

Translation drivers

Translation drivers required when need to get local names of iso entities.

Translation driver must implementSokil\IsoCodes\TranslationDriver\TranslationDriverInterface.

Instance of driver may be passed toIsoCodesFactory. If it not passed, defaultGettextExtensionDriver will be used.

<?php// gettext driver$isoCodes =newIsoCodesFactory();$isoCodes =newIsoCodesFactory(null,newGettextExtensionDriver());// symfony driver$driver =newSymfonyTranslationDriver();// You can also specify a cache directory for better performance. If you are// using the SymfonyTranslationDriver within a Symfony project, you can inject// the `%kernel.cache_dir%/translations` value.$cacheDir ='...';$driver =newSymfonyTranslationDriver($cacheDir)$driver->setLocale('uk_UA');$isoCodes =newIsoCodesFactory(null,$driver);// dummy driver$isoCodes =newIsoCodesFactory(null,newDummyDriver());

Gettext extension driver

This is default translation driver. It requiresext-gettext.

<?php// gettext driver$isoCodes =newIsoCodesFactory();$isoCodes =newIsoCodesFactory(null,newGettextExtensionDriver());

Locale configuration

Before using IsoCodes database you need to setup valid locale to get translations worked,becauseext-gettext uses system local, configured bysetlocale.

<?php// define localeputenv('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 languageecho$languages->getByAlpha2('uk')->getLocalName();// will print 'українська'

To get list of available locales, execute under console:

$ locale -a

uk_UAuk_UA.koi8uuk_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... doneGeneration complete.

Symfony Translation driver

<?php$driver =newSymfonyTranslationDriver();$driver->setLocale('uk_UA');$isoCodes =newIsoCodesFactory(null,$driver);

Dummy driver

This driver may be used, when localisation of names does not require, and only database of codes is required.

<?php$isoCodes =newIsoCodesFactory(null,newDummyDriver());

Usage

Factory

All databases may be created through factory:

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

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 needto 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 saveentry 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)

Country contains next names:

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:

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

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

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 alpha3 code:

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

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

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

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 =newIsoCodesFactory();$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 =newIsoCodesFactory();$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 =newIsoCodesFactory();$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 =newIsoCodesFactory();$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 =newIsoCodesFactory();$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:

./tests/docker/run-test.sh [PHP_VERSION]

For example for PHP 7.1 run following command:

./tests/docker/run-test.sh 7.1

About

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

sokil.github.io/php-isocodes/