README

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

简介

IdnaConvert 库允许将国际化域名（详见 RFC 3492、RFC 5890、RFC 5891、RFC 5892、RFC 5893、RFC 5894、RFC 6452，详情）转换为原始（本地化）形式和编码形式，以便在全球各种注册处使用。

该库提供了两个类（分别是 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 以外的编码字符串，您可能需要在使用 IDNA 转换器之前将这些字符串转换为 UTF-8。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 上的 issues 标签 报告任何错误或功能请求。

联系作者

对于问题、错误报告和安全问题，请给我发送电子邮件。

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

德国

mailto:[email protected]