README

PHP ISO 代码

⭐ 此库用于获取国家、货币、语言和脚本的本地化名称。

📦 基于 Python 的 pycountry 和 Debian 的 iso-codes。

👅 当前翻译状态： https://salsa.debian.org/iso-codes-team/iso-codes#status-of-translations

目录

• ISO 标准
• 安装
• 翻译驱动程序
  • Gettext 扩展驱动程序
    • 区域设置配置
  • Symfony 翻译驱动程序
  • 模拟驱动程序
• 使用
  • 区域设置配置
  • 国家数据库（ISO 3166-1）
  • 子区域数据库（ISO 3166-2）
  • 历史国家数据库（ISO 3166-3）
  • 脚本数据库（ISO 15924）
  • 货币数据库（ISO 4217）
  • 语言数据库（ISO 639-3）
• 测试

ISO 标准

• ISO 3166-1：国家代码（alpha-2、alpha-3、数字）
• ISO 3166-2：所有在 ISO 3166-1 中编码的国家的主要子区域（例如，省份或州）
• ISO 3166-3：历史国家（alpha-2、alpha-3、alpha-4、数字）
• ISO 15924：脚本
• ISO 4217：货币
• ISO 639-3：语言

安装

您可以使用此库以不同的模式使用

• sokil/php-isocodes（此库）- 安装库而不包含数据库和消息，并自行通过 cron 或在 CI/CD 管道中使用 ./bin/update_iso_codes_db.sh 设置数据库和消息的定期更新
• sokil/php-isocodes-db-only - 如果您不需要国际化，请使用此库。数据库已内置。要更新数据库，只需定期更新此库。
• sokil/php-isocodes-db-i18n - 如果您需要国际化，请使用此库。数据库和消息已内置。要更新数据库，只需定期更新此库。

💾 包含数据库和本地化的库

要安装 包含数据库和 i18n 的库

composer require sokil/php-isocodes-db-i18n

💾 包含数据库而不包含本地化的库

您还可以安装 仅包含数据库的库（将不可用 i18n）

composer require sokil/php-isocodes-db-only

💾 不包含数据库和本地化的库，需要手动安装和更新数据库

您可以通过 Composer 安装库

composer require sokil/php-isocodes

数据库和 gettext 文件位于 databases 和 messages 目录中的相关包内。此包与包版本增量定期更新。

如果您想更新数据库，请使用脚本 ./bin/update_iso_codes_db.sh。通过 cron、部署过程或构建您的 docker 映像来调用此脚本。

./bin/update_iso_codes_db.sh {mode} {base_dir} {build_dir}

现在您需要配置工厂以使用此目录

<?php

$databaseBaseDir = '/var/isocodes';

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

翻译驱动程序

• Gettext 扩展驱动程序
  • 区域设置配置
• Symfony 翻译驱动程序
• 模拟驱动程序

在需要获取 iso 实体的本地名称时需要翻译驱动程序。

翻译驱动程序必须实现 Sokil\IsoCodes\TranslationDriver\TranslationDriverInterface。

可以将驱动程序的实例传递给 IsoCodesFactory。如果没有传递，则默认使用 GettextExtensionDriver。

<?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 扩展驱动程序

这是默认的翻译驱动程序。它需要 ext-gettext。

<?php

// gettext driver
$isoCodes = new IsoCodesFactory();
$isoCodes = new IsoCodesFactory(null, new GettextExtensionDriver());

区域设置配置

在使用 IsoCodes 数据库之前，您需要设置有效的区域设置以使翻译正常工作，因为 ext-gettext 使用系统区域设置，由 setlocale 配置。

<?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 'українська'

要获取可用区域设置的列表，请在控制台执行

$ locale -a

uk_UA
uk_UA.koi8u
uk_UA.utf8

如果您在列表中看不到所需的区域设置，您可能需要手动安装它们（针对Ubuntu）

$ locale-gen uk_UA.utf8

Generating locales...
  uk_UA.utf-8... done
Generation complete.

Symfony 翻译驱动程序

<?php

$driver = new SymfonyTranslationDriver();
$driver->setLocale('uk_UA');

$isoCodes = new IsoCodesFactory(
    null,
    $driver
);

模拟驱动程序

当不需要名称本地化，而只需要代码数据库时，可以使用此驱动程序。

<?php

$isoCodes = new IsoCodesFactory(
    null,
    new DummyDriver()
);

使用

• 工厂
• 国家数据库（ISO 3166-1）
• 子区域数据库（ISO 3166-2）
• 历史国家数据库（ISO 3166-3）
• 脚本数据库（ISO 15924）
• 货币数据库（ISO 4217）
• 语言数据库（ISO 639-3）

工厂

所有数据库都可以通过工厂创建。

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

存在大型数据库：子划分和语言。将整个数据库加载到内存中可能需要大量的RAM和创建内存中所有条目所需的时间。

因此存在使用场景：优化内存和使用优化时间。

内存优化

数据库拆分为分区文件。

检索某些条目将仅加载数据库的一小部分。加载的条目不会静态存储。

当只需要加载少量条目时，此场景可能很有用，例如在Web请求中检索一个条目时。

这可能需要大量的文件读取操作。

输入输出优化

整个数据库从单个JSON文件中一次加载到内存中。

所有条目都创建并存储到RAM中。下一次读取或保存条目时，将直接返回它，而不进行与文件的io操作和对象构建。

此场景可能适用于守护进程以减少文件操作，或者当大多数条目将从数据库中检索时。

这可能需要大量的RAM来存储所有条目。

国家数据库（ISO 3166-1）

国家包含以下名称

这些名称可以从国家实体中获取

$isoCodes = new \Sokil\IsoCodes\IsoCodesFactory();
$country = $isoCodes->getCountries()->getByAlpha2('UA');
echo $country->getName();
echo $country->getLocalName();
echo $country->getOfficialName();
echo $country->getCommonName();

您还可以获取国家的国旗

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

通过其alpha2代码获取国家的本地化名称

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

通过其alpha2代码获取国家的本地化名称

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

通过其数字代码获取国家的本地化名称

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

获取国家列表的本地化

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

子区域数据库（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'

历史国家数据库（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

脚本数据库（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

货币数据库（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

语言数据库（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

测试

要开始运行Docker测试，请运行以下命令

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

例如，对于PHP 7.1，请运行以下命令

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

另请参阅

• 乌克兰行政和领土结构对象分类器 - 生成乌克兰城市和居民点详细列表的数据库
• Symfony的PHP替代层C intl扩展，同时也提供了对ICU库本地化数据的访问
• 带国旗的FamFacFam图标包