Added documentation for the PECL idn extension.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@272918 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Christian Hammers 2009-01-06 21:53:16 +00:00
parent 61009f285e
commit e640d48fe9
8 changed files with 652 additions and 0 deletions

45
reference/idn/book.xml Normal file
View file

@ -0,0 +1,45 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<!-- Purpose: international -->
<!-- Membership: pecl, external -->
<book xml:id="book.idn" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<titleabbrev>idn</titleabbrev>
<title>International Domain Names</title>
<preface xml:id="intro.idn">
&reftitle.intro;
<para>
This extension gives access to the GNU Libidn which is
an implementation of the Stringprep, Punycode and IDNA specifications
defined by the IETF Internationalized Domain Names (IDN) working
group, used for internationalized domain names.
</para>
</preface>
&reference.idn.setup;
&reference.idn.constants;
&reference.idn.reference;
</book>
<!-- 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:"../../../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
-->

133
reference/idn/constants.xml Normal file
View file

@ -0,0 +1,133 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<appendix xml:id="idn.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
<variablelist>
<varlistentry>
<term>
<constant>IDNA_STRINGPREP_ERROR</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_PUNYCODE_ERROR</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_CONTAINS_NON_LDH</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_CONTAINS_MINUS</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_INVALID_LENGTH</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_NO_ACE_PREFIX</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_ROUNDTRIP_VERIFY_ERROR</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_CONTAINS_ACE_PREFIX</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_ICONV_ERROR</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>IDNA_MALLOC_ERROR</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>
<!-- 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:"../../../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
-->

View file

@ -0,0 +1,75 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="function.idn-strerror" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>idn_strerror</refname>
<refpurpose>Returns string describing the IDNA error code</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>idn_strerror</methodname>
<methodparam><type>integer</type><parameter>errorcode</parameter></methodparam>
</methodsynopsis>
<para>
This function returns the error message string that corresponds to the given error code.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>errorcode</parameter></term>
<listitem>
<para>
The error code as returned by <function>idn_to_ascii</function> or <function>idn_to_utf8</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The corresponding libidn error message string is returned.
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>idn_to_ascii</function></member>
<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:"../../../../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
-->

View file

@ -0,0 +1,139 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="function.idn-to-ascii" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>idn_to_ascii</refname>
<refpurpose>Convert UTF-8 encoded domain name to ASCII</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>idn_to_ascii</methodname>
<methodparam><type>string</type><parameter>utf8_domain</parameter></methodparam>
<methodparam choice="opt"><type>integer</type><parameter role="reference">errorcode</parameter></methodparam>
</methodsynopsis>
<para>
This function converts a UTF-8 encoded domain name to ASCII according to the IDNA toUnicode() specification.
If the input has non-ASCII characters, the output will be in the "xn--" ACE notation.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>utf8_domain</parameter></term>
<listitem>
<para>
The UTF-8 encoded domain name.
<warning>
<para>
If e.g. an ISO-8859-1 (aka Western Europe latin1) encoded string is
passed it will be converted into an ACE encoded "xn--" string.
It will not be the one you expected though!
</para>
</warning>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errorcode</parameter></term>
<listitem>
<para>
Will be set to the IDNA error code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<!-- See also &return.success; -->
<para>
The ACE encoded version of the domain name or &false; in case of an error.
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
If an error occurs &false; is returned and the optional errorcode is set.
In addition a E_WARNING message is printed.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>idn_to_ascii</function> example</title>
<para>
First a simple example and then one explaining how to catch errors.
</para>
<programlisting role="php">
<![CDATA[
<?php
// ISO-8859-1 encoded string
echo idn_to_ascii(utf8_encode('täst.de')));
// Cannot convert a domain name to ASCII that contains non-ASCII chars but already starts with "xn--"
$ascii = idn_to_ascii("xn--".chr(0xC3).chr(0xA4), $errorcode);
if ($ascii === false) {
printf("Detected error %d: %s\n", $errorcode, idn_strerror($errorcode));
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
xn--tst-qla.de
Detected error 8: Input already contain ACE prefix (`xn--')
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>utf8_encode</function></member>
<member><function>idn_strerror</function></member>
<member><function>itn_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:"../../../../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
-->

View file

@ -0,0 +1,130 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="function.idn-to-utf8" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>idn_to_utf8</refname>
<refpurpose>Convert ASCII encoded domain name to UTF-8</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>idn_to_utf8</methodname>
<methodparam><type>string</type><parameter>ascii_domain</parameter></methodparam>
<methodparam choice="opt"><type>integer</type><parameter role="reference">errorcode</parameter></methodparam>
</methodsynopsis>
<para>
This function converts a ASCII encoded domain name to its original UTF-8 version.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>ascii_domain</parameter></term>
<listitem>
<para>
The ASCII encoded domain name. Looks like "xn--..." if the it originally contained non-ASCII characters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>errorcode</parameter></term>
<listitem>
<para>
Will be set to the IDNA error code.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
The UTF-8 encoded version of the domain name or &false; in case of an error.
RFC 3490 4.2 states though "ToUnicode never fails. If any step fails, then the original input
sequence is returned immediately in that step."
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
<para>
If an error occurs &false; is returned and the optional errorcode is set.
In addition a E_WARNING message is printed.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>idn_to_utf8</function> example</title>
<para>
First a simple example and then one explaining how to catch errors (which should never happen according to the RFC).
</para>
<programlisting role="php">
<![CDATA[
<?php
// maybe convert the result to ISO-8859-1 using utf8_decode()
echo idn_to_utf8("xn--tst-qla.de");
// Should never happen but to be sure...
$utf8 = idn_to_utf8("xn--tst-qla.de", $errorcode);
if ($utf8 === false) {
printf("Detected error %d: %s\n", $errorcode, idn_strerror($errorcode));
}
?>
]]>
</programlisting>
&example.outputs.similar;
<screen>
<![CDATA[
täst.de
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>utf8_decode</function></member>
<member><function>idn_strerror</function></member>
<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:"../../../../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
-->

View file

@ -0,0 +1,31 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<reference xml:id="ref.idn" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Idn &Functions;</title>
&reference.idn.entities.functions;
</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:"../../../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
-->

66
reference/idn/setup.xml Normal file
View file

@ -0,0 +1,66 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<chapter xml:id="idn.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="idn.requirements">
&reftitle.required;
<para>
The GNU <link xlink:href="&url.idn;">IDN library</link> must be installed.
</para>
</section>
<!-- }}} -->
<!-- {{{ Installation -->
<section xml:id="idn.install">
&reftitle.install;
<para>
&pecl.moved;
</para>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;idn">&url.pecl.package;idn</link>.
</para>
</section>
<!-- }}} -->
<!-- {{{ Configuration -->
<section xml:id="idn.configuration">
&reftitle.runtime;
&no.config;
</section>
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="idn.resources">
&reftitle.resources;
&no.resource;
</section>
<!-- }}} -->
</chapter>
<!-- 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:"../../../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
-->

View file

@ -0,0 +1,33 @@
<?xml version='1.0' encoding='utf-8'?>
<!-- $Revision: 1.1 $ -->
<!--
Do NOT translate this file
-->
<versions>
<!-- Functions -->
<function name='idn_strerror' from='PECL idn &gt;= 0.2'/>
<function name='idn_to_ascii' from='PECL idn &gt;= 0.1'/>
<function name='idn_to_utf8' from='PECL idn &gt;= 0.1'/>
<!-- Methods -->
</versions>
<!-- 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:"../../../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
-->