ext/idn - PHP Extension for GNU Libidn

Abstract:
---------
This extension gives access to the GNU Libidn. GNU Libidn 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 which is 
available under the GNU Lesser General Public License. 
More information on GNU Libidn can be found on he GNU website at
http://www.gnu.org/software/libidn/

License:
--------
PHP License 3.0

Requirements:
-------------
GNU Libidn (tested versions: 0.3.7 and 1.8)

Install:
--------
Either using the PEAR Installer:

  $ pear install idn-x.y.tar.gz

Or by hand:

  $ tar xvzf idn-x.y.tar.gz
  $ cd idn-x.y
  $ phpize
  $ ./configure --with-idn
  $ make
  $ make install

Usage:
------
This extension exports currently two functions:
idn_to_ascii() converts an UTF-8 encoded domain name to it's corresponding
Punycode ("xn--") representation.
idn_to_utf8() converts the Punycode version to UTF-8 encoding. 

The functions return a string on success and FALSE as well as an E_WARNING
when an error happens. An errorcode can be retrieved by passing a second 
paramter by reference.

Example:
--------
<?php
$in = 'www..com';
echo idn_to_ascii(utf8_encode($in)); // echos www.xn--4caib6c.com

$in = 'www.xn--4caib6c.com';
echo utf8_decode(idn_to_utf8($in));  // echos www..com

$ascii = @idn_to_ascii("xn--ä", $errorcode);
if ($ascii === false) printf("Detected error %d: %s\n", $errorcode, idn_strerror($errorcode));

$german_domain = idn_to_ascii("tst.de", $errorcode)
?>

Further examples are in the test/ directory.


Caveat:
-------
Be aware that libidn does not complain if a ISO-8859-1 string like "tst.de",
is passed to idn_to_utf8(). The output xn--t-p75a.de will look sane but 
xn--tst-qla.de was expected!  


Author:
-------
Johannes Schlueter
johannes at php dot net
