README

项目主页: http://idnaconv.net
作者: Matthias Sommerfeld matthias.sommerfeld@algo26.de

简介

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 = 'andre@xn--brse-5qa.xn--knrz-1ra.info';  
// 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()会导致损坏的路径或查询字符串。这里public方法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:secret@xn--nrgler-wxa.com/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
Wichertstr. 5
D-10439 Berlin

德国

mailto:matthias.sommerfeld@algo26.de