{"id":15584161,"url":"https://github.com/sokil/php-isocodes","last_synced_at":"2025-05-15T08:00:30.095Z","repository":{"id":17354664,"uuid":"20126248","full_name":"sokil/php-isocodes","owner":"sokil","description":":star: 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)","archived":false,"fork":false,"pushed_at":"2024-12-11T13:13:27.000Z","size":72341,"stargazers_count":175,"open_issues_count":10,"forks_count":13,"subscribers_count":4,"default_branch":"4.0","last_synced_at":"2025-04-14T13:05:10.960Z","etag":null,"topics":["countries","country-codes","currencies","currencies-database","currency","gettext","iso-codes","iso15924","iso3166","iso3166-1","iso3166-2","iso4217","iso639","iso639-3","l10n","language","php","translation"],"latest_commit_sha":null,"homepage":"http://sokil.github.io/php-isocodes/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"xoxco/jQuery-Tags-Input","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sokil.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-05-24T09:28:17.000Z","updated_at":"2025-04-11T14:58:47.000Z","dependencies_parsed_at":"2024-06-18T12:27:31.514Z","dependency_job_id":"8cbcc1fa-a433-471a-8098-37f5efd095a9","html_url":"https://github.com/sokil/php-isocodes","commit_stats":{"total_commits":337,"total_committers":10,"mean_commits":33.7,"dds":"0.13946587537091992","last_synced_commit":"308acfc76081ce10b0714aa2c33606071344c0ef"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-isocodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-isocodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-isocodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sokil%2Fphp-isocodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sokil","download_url":"https://codeload.github.com/sokil/php-isocodes/tar.gz/refs/heads/4.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301420,"owners_count":22047901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["countries","country-codes","currencies","currencies-database","currency","gettext","iso-codes","iso15924","iso3166","iso3166-1","iso3166-2","iso4217","iso639","iso639-3","l10n","language","php","translation"],"created_at":"2024-10-02T20:23:17.681Z","updated_at":"2025-05-15T08:00:30.036Z","avatar_url":"https://github.com/sokil.png","language":"PHP","readme":"# Stand With Ukraine 🇺🇦\n\n[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)\n\n----\n\n# PHP ISO Codes\n\n[![Continuous integration](https://github.com/sokil/php-isocodes/workflows/Continuous%20integration/badge.svg?branch=4.0)](https://github.com/sokil/php-isocodes/actions?query=workflow%3A%22Continuous+integration%22)\n[![Latest Stable Version](https://poser.pugx.org/sokil/php-isocodes/v/stable.png?1)](https://packagist.org/packages/sokil/php-isocodes)\n[![Coverage Status](https://coveralls.io/repos/sokil/php-isocodes/badge.png)](https://coveralls.io/r/sokil/php-isocodes)\n[![Total Downloads](http://img.shields.io/packagist/dt/sokil/php-isocodes.svg?1)](https://packagist.org/packages/sokil/php-isocodes)\n[![Daily Downloads](https://poser.pugx.org/sokil/php-isocodes/d/daily)](https://packagist.org/packages/sokil/php-isocodes/stats)\n\n:star: This library used to get localized names of countries, currencies, languages and scripts.\n\n:package: Based on Python's [pycountry](https://pypi.python.org/pypi/pycountry) and Debian's [iso-codes](https://salsa.debian.org/iso-codes-team/iso-codes.git).\n\n:tongue: Current translation status: https://salsa.debian.org/iso-codes-team/iso-codes#status-of-translations\n\n## Table of contents\n\n* [ISO Standards](#iso-standards)\n* [Installation](#installation)\n* [Translation drivers](#translation-drivers)\n  * [Gettext extension driver](#gettext-extension-driver)\n    * [Locale configuration](#locale-configuration)\n  * [Symfony Translation driver](#symfony-translation-driver)\n  * [Dummy driver](#dummy-driver)\n* [Usage](#usage)\n  * [Locale configuration](#locale-configuration)\n  * [Countries database (ISO 3166-1)](#countries-database-iso-3166-1)\n  * [Subdivisions database (ISO 3166-2)](#subdivisions-database-iso-3166-2)\n  * [Historic countries database (ISO 3166-3)](#historic-countries-database-iso-3166-3)\n  * [Scripts database (ISO 15924)](#scripts-database-iso-15924)\n  * [Currencies database (ISO 4217)](#currencies-database-iso-4217)\n  * [Languages database (ISO 639-3)](#languages-database-iso-639-3)\n* [Tests](#tests)\n\n## ISO Standards\n\n* **ISO 3166-1**: Country codes (alpha-2, alpha-3, numeric)\n* **ISO 3166-2**: Principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1\n* **ISO 3166-3**: Historic countries (alpha-2, alpha-3, alpha-4, numeric)\n* **ISO 15924**: Scripts\n* **ISO 4217**: Currencies\n* **ISO 639-3**: Languages\n\n## Installation\n\nYou may use this library in different modes:\n\n* `sokil/php-isocodes` (this library) - install library without database and messages and setup \n  periodic updates of database and messages by yourself with cron or inside CI/CD pipeline with `./bin/update_iso_codes_db.sh`\n* [sokil/php-isocodes-db-only](https://github.com/sokil/php-isocodes-db-only) - if you do not need internationalisation, use \n  this library. Database already inside. To update database just periodically update this library.\n* [sokil/php-isocodes-db-i18n](https://github.com/sokil/php-isocodes-db-i18n) - if you need internationalisation, use\n  this library. Database and messages already inside. To update database \n  just periodically update this library.\n\n#### 💾 Library with included database and localization\n\nTo install [library with database and i18n](https://github.com/sokil/php-isocodes-db-i18n):\n\n[![Latest Stable Version](https://poser.pugx.org/sokil/php-isocodes-db-i18n/v/stable.png)](https://packagist.org/packages/sokil/php-isocodes-db-i18n)\n[![Total Downloads](http://img.shields.io/packagist/dt/sokil/php-isocodes-db-i18n.svg?1)](https://packagist.org/packages/sokil/php-isocodes-db-i18n)\n[![Daily Downloads](https://poser.pugx.org/sokil/php-isocodes-db-i18n/d/daily)](https://packagist.org/packages/sokil/php-isocodes-db-i18n/stats)\n\n```\ncomposer require sokil/php-isocodes-db-i18n\n```\n\n#### 💾 Library with included database and without localization\n\nYou may also install [library with only database](https://github.com/sokil/php-isocodes-db-only) (no i18n will be available):\n\n[![Latest Stable Version](https://poser.pugx.org/sokil/php-isocodes-db-only/v/stable.png)](https://packagist.org/packages/sokil/php-isocodes-db-only)\n[![Total Downloads](http://img.shields.io/packagist/dt/sokil/php-isocodes-db-only.svg?1)](https://packagist.org/packages/sokil/php-isocodes-db-only)\n[![Daily Downloads](https://poser.pugx.org/sokil/php-isocodes-db-only/d/daily)](https://packagist.org/packages/sokil/php-isocodes-db-only/stats)\n\n```\ncomposer require sokil/php-isocodes-db-only\n```\n\n#### 💾 Library without database and localization, requires manual database installation and updates\n\nYou can install library through Composer:\n\n```\ncomposer require sokil/php-isocodes\n```\n\nDatabase and gettext files located in related packages inside `databases` and `messages` directories.\nThis packages periodically updated with package version increment.\n\nIf you want to update database, use script `./bin/update_iso_codes_db.sh`.\nCall this script by cron, during deploy process or when build your docker image.\n\n```\n./bin/update_iso_codes_db.sh {mode} {base_dir} {build_dir}\n```\n\n| Argument | Required | Description |\n| -------- | -------- | ----------- |\n| 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 |\n| base_dir| Required | Dir where to place database and messages |\\\n| build_dir | Optional. Default: \"/tmp/iso-codes-build\" | Dir where source directory cloned and files original files processed. |\n\nNow you need to configure factory to use this directory:\n\n```php\n\u003c?php\n\n$databaseBaseDir = '/var/isocodes';\n\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory($databaseBaseDir);\n```\n\n## Translation drivers\n\n* [Gettext extension driver](#gettext-extension-driver)\n  * [Locale configuration](#locale-configuration)\n* [Symfony Translation driver](#symfony-translation-driver)\n* [Dummy driver](#dummy-driver)\n  \nTranslation drivers required when need to get local names of iso entities.\n\nTranslation driver must implement `Sokil\\IsoCodes\\TranslationDriver\\TranslationDriverInterface`.\n\nInstance of driver may be passed to `IsoCodesFactory`. If it not passed, default `GettextExtensionDriver` will be used.\n\n```php\n\u003c?php\n\n// gettext driver\n$isoCodes = new IsoCodesFactory();\n$isoCodes = new IsoCodesFactory(null, new GettextExtensionDriver());\n\n// symfony driver\n$driver = new SymfonyTranslationDriver();\n$driver-\u003esetLocale('uk_UA');\n\n$isoCodes = new IsoCodesFactory(\n    null,\n    $driver\n);\n\n// dummy driver\n$isoCodes = new IsoCodesFactory(\n    null,\n    new DummyDriver()\n);\n\n```\n\n### Gettext extension driver\n\nThis is default translation driver. It requires `ext-gettext`.\n\n```php\n\u003c?php\n\n// gettext driver\n$isoCodes = new IsoCodesFactory();\n$isoCodes = new IsoCodesFactory(null, new GettextExtensionDriver());\n```\n\n#### Locale configuration\n\nBefore using IsoCodes database you need to setup valid locale to get translations worked, \nbecause `ext-gettext` uses system local, configured by `setlocale`.\n\n```php\n\u003c?php\n\n// define locale\nputenv('LANGUAGE=uk_UA.UTF-8');\nputenv('LC_ALL=uk_UA.UTF-8');\nsetlocale(LC_ALL, 'uk_UA.UTF-8');\n\n// init database\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n\n// get languages database\n$languages = $isoCodes-\u003egetLanguages();\n\n// get local name of language\necho $languages-\u003egetByAlpha2('uk')-\u003egetLocalName(); // will print 'українська'\n```\n\nTo get list of available locales, execute under console:\n```sh\n$ locale -a\n```\n```\nuk_UA\nuk_UA.koi8u\nuk_UA.utf8\n```\n\nIf you don't see required locales in list, you may install them manually (for Ubuntu):\n```sh\n$ locale-gen uk_UA.utf8\n```\n```\nGenerating locales...\n  uk_UA.utf-8... done\nGeneration complete.\n```\n\n### Symfony Translation driver\n\n```php\n\u003c?php\n\n$driver = new SymfonyTranslationDriver();\n$driver-\u003esetLocale('uk_UA');\n\n$isoCodes = new IsoCodesFactory(\n    null,\n    $driver\n);\n\n```\n\n### Dummy driver\n\nThis driver may be used, when localisation of names does not require, and only database of codes is required.\n\n```php\n\u003c?php\n\n$isoCodes = new IsoCodesFactory(\n    null,\n    new DummyDriver()\n);\n```\n\n## Usage\n\n* [Factory](#factory)\n* [Countries database (ISO 3166-1)](#countries-database-iso-3166-1)\n* [Subdivisions database (ISO 3166-2)](#subdivisions-database-iso-3166-2)\n* [Historic countries database (ISO 3166-3)](#historic-countries-database-iso-3166-3)\n* [Scripts database (ISO 15924)](#scripts-database-iso-15924)\n* [Currencies database (ISO 4217)](#currencies-database-iso-4217)\n* [Languages database (ISO 639-3)](#languages-database-iso-639-3)\n\n### Factory\n\nAll databases may be created through factory:\n\n```php\n\u003c?php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$languages = $isoCodes-\u003egetLanguages();\n```\n\nThere are large databases: subdivisions and languages.\nLoading of entire database into memory may require lot of RAM and time to create all entries in memory.\n  \nSo there are scenarios of usage: with optimisations of memory and with optimisation of time.\n\n#### Memory optimisation\n\nDatabase splits into partition files.\n\nFetching some entry will load only little part of database.\nLoaded entries not stored statically.\n\nThis scenario may be useful when just few entries need\nto be loaded, for example on web request when one entry fetched.\n\nThis may require a lot of file read operations.\n     \n#### Input-output optimisations\n\nEntire database loaded into memory from single JSON file once.\n\nAll entries created and stored into RAM. Next read of save\nentry will just return it without io operations with files and building objects.\n\nThis scenario may be useful for daemons to decrease file operations,\nor when most entries will be fetched from database.\n\nThis may require a lot of RAM for storing all entries.\n     \n### Countries database (ISO 3166-1)\n\nCountry contains next names:\n\n| Name           | Description | Example              |\n|----------------|-------------|----------------------|\n| Name           | Required    | Moldova, Republic of |\n| Official Name  | Optional    | Republic of Moldova  |\n| Common Name    | Optional    | Moldova              |\n| Localised Name | Optional    | Молдова              |\n\nThis names may be get from country entity:\n\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$country = $isoCodes-\u003egetCountries()-\u003egetByAlpha2('UA');\necho $country-\u003egetName();\necho $country-\u003egetLocalName();\necho $country-\u003egetOfficialName();\necho $country-\u003egetCommonName();\n```\n\nAlso you may get flag of country:\n\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$country = $isoCodes-\u003egetCountries()-\u003egetByAlpha2('UA');\necho $country-\u003egetFlag();\n```\n\nGet localized name of country by it's alpha2 code:\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$isoCodes-\u003egetCountries()-\u003egetByAlpha2('UA')-\u003egetLocalName();\n```\n\nGet localized name of country by it's alpha3 code:\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$isoCodes-\u003egetCountries()-\u003egetByAlpha3('UKR')-\u003egetLocalName();\n```\n\nGet localized name of country by it's numeric code:\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\n$isoCodes-\u003egetCountries()-\u003egetByNumericCode('804')-\u003egetLocalName();\n```\n\nGet  localised list of countries\n```php\n$isoCodes = new \\Sokil\\IsoCodes\\IsoCodesFactory();\nforeach($isoCodes-\u003egetCountries() as $country) {\n  echo $country-\u003egetLocalName();\n}\n```\n\n### Subdivisions database (ISO 3166-2)\n\n```php\n\u003c?php\n\n$isoCodes = new IsoCodesFactory();\n\n$subDivisions = $isoCodes-\u003egetSubdivisions();\n\n// get subdivision by code\n$subDivision = $subDivisions-\u003egetByCode('UA-43');\n\n// get subdivision code\n$subDivision-\u003egetCode(); // UA-43\n\n// get subdivision name\n$subDivision-\u003egetName(); // Respublika Krym\n\n// get localised subdivision name\n$subDivision-\u003egetLocalName(); // Автономна Республіка Крим\n\n// get subdivision type\n$subDivision-\u003egetType(); // 'Autonomous republic'\n```\n\n### Historic countries database (ISO 3166-3)\n\n```php\n\u003c?php\n\n$isoCodes = new IsoCodesFactory();\n\n$countries = $isoCodes-\u003egetHistoricCountries();\n\n$country = $countries-\u003egetByAlpha4('ZRCD');\n\n$country-\u003egetName(); //'Zaire, Republic of'\n$country-\u003egetAlpha4(); // 'ZRCD'\n$country-\u003egetAlpha3(); // 'ZAR'\n$country-\u003egetAlpha2(); // 'ZR'\n$country-\u003egetWithdrawalDate(); // '1997-07-14'\n$country-\u003egetNumericCode(); // 180\n```\n\n### Scripts database (ISO 15924)\n\n```php\n\u003c?php\n$isoCodes = new IsoCodesFactory();\n\n$scripts = $isoCodes-\u003egetScripts();\n\n$script = $scripts-\u003egetByAlpha4('Aghb');\n\n$script-\u003egetName(); // Caucasian Albanian\n$script-\u003egetLocalName(); // кавказька албанська\n$script-\u003egetAlpha4(); // Aghb\n$script-\u003egetNumericCode(); 239\n```\n\n### Currencies database (ISO 4217)\n\n```php\n\u003c?php\n\n$isoCodes = new IsoCodesFactory();\n\n$currencies = $isoCodes-\u003egetCurrencies();\n\n$currency = $currencies-\u003egetByLetterCode('CZK');\n\n$currency-\u003egetName(); // Czech Koruna\n$currency-\u003egetLocalName(); // Чеська крона\n$currency-\u003egetLetterCode(); // CZK\n$currency-\u003egetNumericCode(); // 203\n```\n\n### Languages database (ISO 639-3)\n\n```php\n\u003c?php\n$isoCodes = new IsoCodesFactory();\n\n$languages = $isoCodes-\u003egetLanguages();\n\n$language = $languages-\u003egetByAlpha2('uk');\n\n$language-\u003egetAlpha2(); // uk\n\n$language-\u003egetName(); // Ukrainian\n\n$language-\u003egetLocalName(); // українська\n\n$language-\u003egetAlpha3(); // ukr\n\n// Scope of denotation, see mote at https://iso639-3.sil.org/about/scope\n$language-\u003egetScope(); // I\n\n// Type of language, see https://iso639-3.sil.org/about/types\n$language-\u003egetType(); // L\n\n$language-\u003egetInvertedName(); // null\n```\n\n## Tests\n\nTo start docker tests run following command:\n```\n./tests/docker/run-test.sh [PHP_VERSION]\n```\n\nFor example for PHP 7.1 run following command:\n```\n./tests/docker/run-test.sh 7.1\n```\n\n\n## See also\n\n* [State Classifier of objects of administrative and territorial structure of Ukraine](https://github.com/sokil/koatuu) - generates database of detailed list of cities and settlements of Ukraine\n* [A Symfony's PHP replacement layer for the C intl extension that also provides access to the localization data of the ICU library](http://symfony.com/doc/current/components/intl.html)\n* [FamFacFam icon pack with flags](http://www.famfamfam.com/lab/icons/flags/)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokil%2Fphp-isocodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsokil%2Fphp-isocodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsokil%2Fphp-isocodes/lists"}