From cd818750dfa4a43de3eb3a0d498c58a93242db1e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=92=8B=E6=96=87=E5=81=A5?= <jwjbjg@gmail.com>
Date: Mon, 1 Feb 2021 23:43:51 +0800
Subject: [PATCH] =?UTF-8?q?=E7=BF=BB=E8=AF=91=20IDN=20=E5=87=BD=E6=95=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 reference/intl/idn.xml              |  29 +++++
 reference/intl/idn/idn-to-ascii.xml | 160 ++++++++++++++++++++++++++++
 reference/intl/idn/idn-to-utf8.xml  | 160 ++++++++++++++++++++++++++++
 3 files changed, 349 insertions(+)
 create mode 100644 reference/intl/idn.xml
 create mode 100644 reference/intl/idn/idn-to-ascii.xml
 create mode 100644 reference/intl/idn/idn-to-utf8.xml

diff --git a/reference/intl/idn.xml b/reference/intl/idn.xml
new file mode 100644
index 000000000..ded6d6a3b
--- /dev/null
+++ b/reference/intl/idn.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- $Author$ -->
+<!-- EN-Revision: 9eed6aef54900ebe7b1266e4d09d9461255a1a18 Maintainer:  Status: ready -->
+<reference xml:id="ref.intl.idn" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <title>IDN &Functions;</title>
+ &reference.intl.entities.idn;
+</reference>
+
+<!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ indent-tabs-mode:nil
+ sgml-parent-document:nil
+ sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+ sgml-exposed-tags:nil
+ sgml-local-catalogs:nil
+ sgml-local-ecat-files:nil
+ End:
+ vim600: syn=xml fen fdm=syntax fdl=2 si
+ vim: et tw=78 syn=sgml
+ vi: ts=1 sw=1
+-->
diff --git a/reference/intl/idn/idn-to-ascii.xml b/reference/intl/idn/idn-to-ascii.xml
new file mode 100644
index 000000000..b227584ae
--- /dev/null
+++ b/reference/intl/idn/idn-to-ascii.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- $Author$ -->
+<!-- EN-Revision: b95d28e6ec86e4a71e012737d36ebdc1cf009180 Maintainer:  Status: ready -->
+<refentry xml:id="function.idn-to-ascii" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>idn_to_ascii</refname>
+  <refpurpose>将域名转换为 IDNA ASCII 格式 </refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <para>&style.procedural;</para>
+  <methodsynopsis>
+   <type class="union"><type>string</type><type>false</type></type><methodname>idn_to_ascii</methodname>
+   <methodparam><type>string</type><parameter>domain</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>IDNA_DEFAULT</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>variant</parameter><initializer>INTL_IDNA_VARIANT_UTS46</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter role="reference">idna_info</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   该函数可以将 Unicode 域名转换为 IDNA ASCII 兼容格式。
+  </para> 
+  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>domain</parameter></term>
+     <listitem>
+      <para>
+       要转换的域，必须使用 UTF-8 编码。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>options</parameter></term>
+     <listitem>
+      <para>
+       转换选项 — IDNA_* 开头的常量（除 IDNA_ERROR_* 开头的常量）。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>variant</parameter></term>
+     <listitem>
+      <para>
+       对于 IDNA 2003 是 <constant>INTL_IDNA_VARIANT_2003</constant> (自 PHP 7.2.0 起已弃用)，
+       对于 UTS #46 是 <constant>INTL_IDNA_VARIANT_UTS46</constant> (仅 ICU 4.6 起可用)。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>idna_info</parameter></term>
+     <listitem>
+      <para>
+       仅当 <constant>INTL_IDNA_VARIANT_UTS46</constant> 用于 <parameter>variant</parameter> 时，才可以使用该参数。
+       在这种情况下，它将用这些键组成的数组来填充：
+       <literal>'result'</literal> 键，转换结果（有可能是一个非法结果）；
+       <literal>'isTransitionalDifferent'</literal> 键，布尔值，指示使用 UTS #46 的过滤机制是否会改变结果；
+       <literal>'errors'</literal> 键，是 IDNA_ERROR_* 常量集里一个常量对应的 <type>int</type> 。
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   IDNA ASCII 兼容格式编码的域名， &return.falseforfailure;
+  </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        现在 <parameter>variant</parameter> 的默认值为 <constant>INTL_IDNA_VARIANT_UTS46</constant> ，
+        而不是已弃用的 <constant>INTL_IDNA_VARIANT_2003</constant> 。
+       </entry>
+      </row>
+      <row>
+       <entry>7.2.0</entry>
+       <entry>
+        <constant>INTL_IDNA_VARIANT_2003</constant> 已被弃用；
+        可以使用 <constant>INTL_IDNA_VARIANT_UTS46</constant> 代替。
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>idn_to_ascii</function> 示例</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+echo idn_to_ascii('täst.de'); 
+
+?>
+]]>
+   </programlisting>
+  </example>
+  &example.outputs;
+  <screen>
+<![CDATA[
+xn--tst-qla.de
+]]>
+  </screen>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>idn_to_utf8</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/intl/idn/idn-to-utf8.xml b/reference/intl/idn/idn-to-utf8.xml
new file mode 100644
index 000000000..cb0b21dd5
--- /dev/null
+++ b/reference/intl/idn/idn-to-utf8.xml
@@ -0,0 +1,160 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!-- $Author$ -->
+<!-- EN-Revision: b95d28e6ec86e4a71e012737d36ebdc1cf009180 Maintainer:  Status: ready -->
+<refentry xml:id="function.idn-to-utf8" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>idn_to_utf8</refname>
+  <refpurpose>将域名从 IDNA ASCII 转换为 Unicode</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <para>&style.procedural;</para>
+  <methodsynopsis>
+   <type class="union"><type>string</type><type>false</type></type><methodname>idn_to_utf8</methodname>
+   <methodparam><type>string</type><parameter>domain</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>IDNA_DEFAULT</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>variant</parameter><initializer>INTL_IDNA_VARIANT_UTS46</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter role="reference">idna_info</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   该函数将 Unicode 域名从 IDNA ASCII 兼容格式转换为 纯 Unicode（UTF-编码）。
+  </para> 
+  </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>domain</parameter></term>
+     <listitem>
+      <para>
+       要转换的 IDNA ASCII 兼容格式的域名。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>options</parameter></term>
+     <listitem>
+      <para>
+       转换选项 — IDNA_* 开头的常量（除 IDNA_ERROR_* 开头的常量）。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>variant</parameter></term>
+     <listitem>
+      <para>
+       对于 IDNA 2003 是 <constant>INTL_IDNA_VARIANT_2003</constant> (自 PHP 7.2.0 起已弃用)，
+       对于 UTS #46 是 <constant>INTL_IDNA_VARIANT_UTS46</constant> (仅 ICU 4.6 起可用)。
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>idna_info</parameter></term>
+     <listitem>
+      <para>
+       仅当 <constant>INTL_IDNA_VARIANT_UTS46</constant> 用于 <parameter>variant</parameter> 时，才可以使用该参数。
+       在这种情况下，它将用这些键组成的数组来填充：
+       <literal>'result'</literal> 键，转换结果（有可能是一个非法结果）；
+       <literal>'isTransitionalDifferent'</literal> 键，布尔值，指示使用 UTS #46 的过滤机制是否会改变结果；
+       <literal>'errors'</literal> 键，是 IDNA_ERROR_* 常量集里一个常量对应的 <type>int</type> 。
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   UTF-8 编码的 Unicode 域名， &return.falseforfailure;
+  </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <para>
+   <informaltable>
+    <tgroup cols="2">
+     <thead>
+      <row>
+       <entry>&Version;</entry>
+       <entry>&Description;</entry>
+      </row>
+     </thead>
+     <tbody>
+      <row>
+       <entry>7.4.0</entry>
+       <entry>
+        现在 <parameter>variant</parameter> 的默认值为 <constant>INTL_IDNA_VARIANT_UTS46</constant> ，
+        而不是已弃用的 <constant>INTL_IDNA_VARIANT_2003</constant> 。
+       </entry>
+      </row>
+      <row>
+       <entry>7.2.0</entry>
+       <entry>
+        <constant>INTL_IDNA_VARIANT_2003</constant> 已被弃用；
+        可以使用 <constant>INTL_IDNA_VARIANT_UTS46</constant> 代替。
+       </entry>
+      </row>
+     </tbody>
+    </tgroup>
+   </informaltable>
+  </para>
+ </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>idn_to_utf8</function> 示例</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+echo idn_to_utf8('xn--tst-qla.de'); 
+
+?>
+]]>
+   </programlisting>
+  </example>
+  &example.outputs;
+  <screen>
+<![CDATA[
+täst.de
+]]>
+  </screen>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>idn_to_ascii</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->