README

项目主页: http://idnaconv.net
由 Matthias Sommerfeld [email protected]

简介

IdnaConvert 库允许将国际化域名（详见 RFC 3492、RFC 5890、RFC 5891、RFC 5892、RFC 5893、RFC 5894、RFC 6452，详情）转换为它们原始（本地化）形式和它们编码形式，后者将在 DNS（域名系统）中使用。

该库提供了两个类（分别命名为 ToIdn 和 ToUnicode），它们分别公开了三个公共方法，用于在相应形式之间进行转换。请参阅下面的示例部分。这允许您转换主机名（如 localhost 或 FQHNs 如 some-host.domain.example）、电子邮件地址和完整的 URL。

错误、编码错误或不正确的字符串将导致各种异常。它们应该有助于您找出问题所在。

预期 Unicode 字符串为 UTF-8 字符串。ACE 字符串（Punycode 形式）始终是 7 位 ASCII 字符串。

安装

通过 Composer

composer require algo26-matthias/idna-convert

官方 ZIP 包

官方 ZIP 包已停止。请坚持使用 Composer 或 GitHub 获取您的副本。

从先前版本升级

请参阅 升级说明 了解从先前版本升级的信息。

示例

示例 1。

假设我们想编码域名 nörgler.com

<?php  
// Include the class
use Algo26\IdnaConvert\ToIdn;
// Instantiate it
$IDN = new ToIdn();
// The input string, if input is not UTF-8 or UCS-4, it must be converted before  
$input = utf8_encode('nörgler.com');  
// Encode it to its punycode presentation  
$output = $IDN->convert($input);  
// Output, what we got now  
echo $output; // This will read: xn--nrgler-wxa.com

示例 2。

我们从国际域名收到了一封电子邮件，并希望将其解码为其 Unicode 形式。

<?php  
// Include the class
use Algo26\IdnaConvert\ToUnicode;
// Instantiate it
$IDN = new ToUnicode();
// The input string  
$input = '[email protected]';  
// Encode it to its punycode presentation  
$output = $IDN->convertEmailAddress($input);  
// Output, what we got now, if output should be in a format different to UTF-8  
// or UCS-4, you will have to convert it before outputting it  
echo utf8_decode($output); // This will read: andre@börse.knörz.info

示例 3。

输入从使用 UCS-4 编码的文件中读取，并逐行编码。通过附加可选的第二个参数，我们告诉 enode() 要使用的输入格式

<?php  
// Include the class
use Algo26\IdnaConvert\ToIdn;
use Algo26\IdnaConvert\TranscodeUnicode\TranscodeUnicode;
// Instantiate
$IDN = new ToIdn();
$UCTC = new TranscodeUnicode();
// Iterate through the input file line by line  
foreach (file('ucs4-domains.txt') as $line) {
    $utf8String = $UCTC->convert(trim($line), 'ucs4', 'utf8');
    echo $IDN->convert($utf8String);
    echo "\n";
}

示例 4。

我们希望将整个 URI 转换为 IDNA 形式，但保留其路径或查询字符串部分。仅使用 encode() 会导致路径或查询字符串损坏。这里公共方法 convertUrl() 就派上用场了

<?php  
// Include the class
use Algo26\IdnaConvert\ToIdn;
// Instantiate it
$IDN = new ToIdn();
// The input string, a whole URI in UTF-8 (!)  
$input = 'http://nörgler:secret@nörgler.com/my_päth_is_not_ÄSCII/');  
// Encode it to its punycode presentation  
$output = $IDN->convertUrl($input);
// Output, what we got now  
echo $output; // http://nörgler:[email protected]/my_päth_is_not_ÄSCII/

示例 5。

默认情况下，该类根据 IDNA 版本 2008 转换字符串。为了支持 IDNA 2003，需要在调用类时添加一个额外的参数。

<?php  
// Include the class  
use Algo26\IdnaConvert\ToIdn;
// Instantiate it, switching to IDNA 2003, the original, now outdated standard
$IDN = new ToIdn(2008);
// Sth. containing the German letter ß  
$input = 'meine-straße.example';
// Encode it to its punycode presentation  
$output = $IDN->convert($input);  
// Output, what we got now  
echo $output; // xn--meine-strae-46a.example
  
// Switch back to IDNA 2008
$IDN = new ToIdn(2003);
// Sth. containing the German letter ß  
$input = 'meine-straße.example';  
// Encode it to its punycode presentation  
$output = $IDN->convert($input);
// Output, what we got now  
echo $output; // meine-strasse.example

编码辅助工具

如果您有除 ISO-8859-1 和 UTF-8 以外的编码字符串，您可能需要在这些字符串转换为 UTF-8 之前将其翻译为 UTF-8，然后再将其输入到 IDNA 转换器中。PHP 内置函数 utf8_encode() 和 utf8_decode() 只能处理 ISO-8859-1。
请使用本软件包提供的编码辅助类进行转换。它需要安装iconv、libiconv或mbstring中的一个，并与其他相关PHP扩展一起安装。您可能会用到的函数是toUtf8()，作为utf8_encode()的替代，以及fromUtf8()，作为utf8_decode()的替代。

示例用法

<?php  
use Algo26\IdnaConvert\ToIdn;
use Algo26\IdnaConvert\EncodingHelper\ToUtf8;

$IDN = new ToIdn();
$encodingHelper = new ToUtf8();

$mystring = $encodingHelper->convert('<something in e.g. ISO-8859-15', 'ISO-8859-15');
echo $IDN->convert($mystring);

UCTC — Unicode转换器

在处理一个或多个Unicode编码类型时，您可能还会发现这个类很有用。它可以将它们相互转换。

• UCS-4字符串/数组
• UTF-8
• UTF-7
• UTF-7 IMAP（修改后的UTF-7）
  所有编码都期望/返回指定格式的字符串，只有一个主要例外：UCS-4数组只是一个数组，其中每个值代表字符串中的一个码点，即每个值都是32位整数。

示例用法

<?php  
use Algo26\IdnaConvert\TranscodeUnicode\TranscodeUnicode;
$transcodeUnicode = new TranscodeUnicode();

$mystring = 'nörgler.com';  
echo $transcodeUnicode->convert($mystring, 'utf8', 'utf7imap');

运行PHPUnit测试

该库附带一个docker-compose.yml文件，允许您运行提供的测试。这假定您已安装Docker，且docker-compose可用为命令。只需在您本地的命令行中执行

docker-compose up

并查看PHPUnit的输出。

报告错误

请使用GitHub上的问题标签来报告任何错误或功能请求。

联系作者

对于问题、错误报告和安全问题，请通过电子邮件联系我。

algo26 Beratungs GmbH
c/o Matthias Sommerfeld
Zedernweg 1
D-16348 Wandlitz

德国

mailto:[email protected]