PHP Classes

IDNA Convert: Convert from and to IDNA Punycode domain names

Recommend this page to a friend!
  Info   Screenshots   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 74%Total: 4,652 All time: 601 This week: 44Up
Version License PHP version Categories
idna_convert 1.0.19GNU Lesser Genera...5.0Localization, Text processing
Description 

Author

IDNA stands for Internationalized Domain Names for Applications. It is a standard described in RFC 3490, RFC 3491 and RFC 3492. It is used to allow language specific characters in domain names, like the umlauts in German, accents in latin languages like French, or even chinese characters.

This class allows you to convert domain names between the encoded Punycode notation and the decoded 8bit (UTF-8) notation. It simplifies the use of domain names defined with IDNA in applications or scripts.

Picture of Matthias Sommerfeld
  Performance   Level  
Name: Matthias Sommerfeld <contact>
Classes: 1 package by
Country: Germany Germany
Age: 49
All time rank: 63541 in Germany Germany
Week rank: 192 Up13 in Germany Germany Up

Details

******************************************************************************* * * * IDNA Convert (idna_convert.class.php) * * * * http://idnaconv.phlymail.de mailto:phlymail@phlylabs.de * ******************************************************************************* * (c) 2004-2011 phlyLabs, Berlin * * This file is encoded in UTF-8 * ******************************************************************************* Introduction ------------ The class idna_convert allows to convert internationalized domain names (see RFC 3490, 3491, 3492 and 3454 for detials) as they can be used with various registries worldwide to be translated between their original (localized) form and their encoded form as it will be used in the DNS (Domain Name System). The class provides two public methods, encode() and decode(), which do exactly what you would expect them to do. You are allowed to use complete domain names, simple strings and complete email addresses as well. That means, that you might use any of the following notations: - www.nörgler.com - xn--nrgler-wxa - xn--brse-5qa.xn--knrz-1ra.info Errors, incorrectly encoded or invalid strings will lead to either a FALSE response (when in strict mode) or to only partially converted strings. You can query the occured error by calling the method get_last_error(). Unicode strings are expected to be either UTF-8 strings, UCS-4 strings or UCS-4 arrays. The default format is UTF-8. For setting different encodings, you can call the method setParams() - please see the inline documentation for details. ACE strings (the Punycode form) are always 7bit ASCII strings. ATTENTION: As of version 0.6.0 this class is written in the OOP style of PHP5. Since PHP4 is no longer actively maintained, you should switch to PHP5 as fast as possible. We expect to see no compatibility issues with the upcoming PHP6, too. ATTENTION: BC break! As of version 0.6.4 the class per default allows the German ligature ß to be encoded as the DeNIC, the registry for .DE allows domains containing ß. In older builds "ß" was mapped to "ss". Should you still need this behaviour, see example 5 below. ATTENTION: As of version 0.8.0 the class fully supports IDNA 2008. Thus the aforementioned parameter is deprecated and replaced by a parameter to switch between the standards. See the updated example 5 below. Files ----- idna_convert.class.php - The actual class example.php - An example web page for converting transcode_wrapper.php - Convert various encodings, see below uctc.php - phlyLabs' Unicode Transcoder, see below ReadMe.txt - This file LICENCE - The LGPL licence file The class is contained in idna_convert.class.php. Examples -------- 1. Say we wish to encode the domain name nörgler.com: // Include the class require_once('idna_convert.class.php'); // Instantiate it $IDN = new idna_convert(); // 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->encode($input); // Output, what we got now echo $output; // This will read: xn--nrgler-wxa.com 2. We received an email from a punycoded domain and are willing to learn, how the domain name reads originally // Include the class require_once('idna_convert.class.php'); // Instantiate it $IDN = new idna_convert(); // The input string $input = 'andre@xn--brse-5qa.xn--knrz-1ra.info'; // Encode it to its punycode presentation $output = $IDN->decode($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. The input is read from a UCS-4 coded file and encoded line by line. By appending the optional second parameter we tell enode() about the input format to be used // Include the class require_once('idna_convert.class.php'); // Instantiate it $IDN = new dinca_convert(); // Iterate through the input file line by line foreach (file('ucs4-domains.txt') as $line) { echo $IDN->encode(trim($line), 'ucs4_string'); echo "\n"; } 4. We wish to convert a whole URI into the IDNA form, but leave the path or query string component of it alone. Just using encode() would lead to mangled paths or query strings. Here the public method encode_uri() comes into play: // Include the class require_once('idna_convert.class.php'); // Instantiate it $IDN = new idna_convert(); // 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->encode_uri($input); // Output, what we got now echo $output; // http://nörgler:secret@xn--nrgler-wxa.com/my_päth_is_not_ÄSCII/ 5. To support IDNA 2008, the class needs to be invoked with an additional parameter. This can also be achieved on an instance. // Include the class require_once('idna_convert.class.php'); // Instantiate it $IDN = new idna_convert(array('idn_version' => 2008)); // Sth. containing the German letter ß $input = 'meine-straße.de'); // Encode it to its punycode presentation $output = $IDN->encode_uri($input); // Output, what we got now echo $output; // xn--meine-strae-46a.de // Switch back to old IDNA 2003, the original standard $IDN->set_parameter('idn_version', 2003); // Sth. containing the German letter ß $input = 'meine-straße.de'); // Encode it to its punycode presentation $output = $IDN->encode_uri($input); // Output, what we got now echo $output; // meine-strasse.de Transcode wrapper ----------------- In case you have strings in different encoding than ISO-8859-1 and UTF-8 you might need to translate these strings to UTF-8 before feeding the IDNA converter with it. PHP's built in functions utf8_encode() and utf8_decode() can only deal with ISO-8859-1. Use the file transcode_wrapper.php for the conversion. It requires either iconv, libiconv or mbstring installed together with one of the relevant PHP extensions. The functions you will find useful are encode_utf8() as a replacement for utf8_encode() and decode_utf8() as a replacement for utf8_decode(). Example usage: <?php require_once('idna_convert.class.php'); require_once('transcode_wrapper.php'); $mystring = '<something in e.g. ISO-8859-15'; $mystring = encode_utf8($mystring, 'ISO-8859-15'); echo $IDN->encode($mystring); ?> UCTC - Unicode Transcoder ------------------------- Another class you might find useful when dealing with one or more of the Unicode encoding flavours. The class is static, it requires PHP5. It can transcode into each other: - UCS-4 string / array - UTF-8 - UTF-7 - UTF-7 IMAP (modified UTF-7) All encodings expect / return a string in the given format, with one major exception: UCS-4 array is jsut an array, where each value represents one codepoint in the string, i.e. every value is a 32bit integer value. Example usage: <?php require_once('uctc.php'); $mystring = 'nörgler.com'; echo uctc::convert($mystring, 'utf8', 'utf7imap'); ?> Contact us ---------- In case of errors, bugs, questions, wishes, please don't hesitate to contact us under the email address above. The team of phlyLabs http://phlylabs.de mailto:phlymail@phlylabs.de

Screenshots (1)  
  • net_idna.png
  Files folder image Files (41)  
File Role Description
Files folder image.github (1 directory)
Files folder imagesrc (4 files, 5 directories)
Files folder imagetests (2 directories)
Accessible without login Plain text file .travis.yml Data Auxiliary data
Accessible without login Plain text file CODE_OF_CONDUCT.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Import from GitHub
Accessible without login Plain text file docker-compose.yml Data Auxiliary data
Accessible without login Plain text file example.php Example Example IDNA converter (run in your browser)
Plain text file idna_convert.class.php Class IDNA Convert 0.8.1
Accessible without login Plain text file LICENCE Lic. The licence file
Accessible without login Plain text file LICENSE Data Import from GitHub
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file README.md Data Import from GitHub
Accessible without login Plain text file ReadMe.txt Doc. The ReadMe file
Accessible without login Plain text file UPGRADING.md Data Auxiliary data

  Files folder image Files (41)  /  .github  
File Role Description
Files folder imageISSUE_TEMPLATE (2 files)

  Files folder image Files (41)  /  .github  /  ISSUE_TEMPLATE  
File Role Description
  Accessible without login Plain text file bug_report.md Data Auxiliary data
  Accessible without login Plain text file feature_request.md Data Auxiliary data

  Files folder image Files (41)  /  src  
File Role Description
Files folder imageEncodingHelper (3 files)
Files folder imageException (4 files)
Files folder imageNamePrep (5 files)
Files folder imagePunycode (4 files)
Files folder imageTranscodeUnicode (3 files)
  Plain text file AbstractIdnaConvert.php Class Class source
  Plain text file IdnaConvertInterface.php Class Class source
  Plain text file ToIdn.php Class Class source
  Plain text file ToUnicode.php Class Class source

  Files folder image Files (41)  /  src  /  EncodingHelper  
File Role Description
  Plain text file EncodingHelperInterface.php Class Class source
  Plain text file FromUtf8.php Class Class source
  Plain text file ToUtf8.php Class Class source

  Files folder image Files (41)  /  src  /  Exception  
File Role Description
  Plain text file AlreadyPunycodeException.php Class Class source
  Plain text file InvalidCharacterException.php Class Class source
  Plain text file InvalidIdnVersionException.php Class Class source
  Plain text file Std3AsciiRulesViolationException.php Class Class source

  Files folder image Files (41)  /  src  /  NamePrep  
File Role Description
  Plain text file NamePrep.php Class Class source
  Plain text file NamePrepData2003.php Class Class source
  Plain text file NamePrepData2008.php Class Class source
  Plain text file NamePrepDataInterface.php Class Class source
  Plain text file NamePrepInterface.php Class Class source

  Files folder image Files (41)  /  src  /  Punycode  
File Role Description
  Plain text file AbstractPunycode.php Class Class source
  Plain text file FromPunycode.php Class Class source
  Plain text file PunycodeInterface.php Class Class source
  Plain text file ToPunycode.php Class Class source

  Files folder image Files (41)  /  src  /  TranscodeUnicode  
File Role Description
  Plain text file ByteLengthTrait.php Class Class source
  Plain text file TranscodeUnicode.php Class Class source
  Plain text file TranscodeUnicodeInterface.php Class Class source

  Files folder image Files (41)  /  tests  
File Role Description
Files folder imageintegration (2 files)
Files folder imageunit (1 file)

  Files folder image Files (41)  /  tests  /  integration  
File Role Description
  Plain text file ToIdnTest.php Class Class source
  Plain text file ToUnicodeTest.php Class Class source

  Files folder image Files (41)  /  tests  /  unit  
File Role Description
  Plain text file namePrepTest.php Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Reuses Unique User Downloads Download Rankings  
 87%1
Total:4,652
This week:0
All time:601
This week:44Up
User Ratings User Comments (3)
 All time
Utility:95%StarStarStarStarStar
Consistency:90%StarStarStarStarStar
Documentation:87%StarStarStarStarStar
Examples:90%StarStarStarStarStar
Tests:-
Videos:-
Overall:74%StarStarStarStar
Rank:97
 
Very well done, fastest and most lightweight mechanisms I've ...
12 years ago (Jamie Booth)
75%StarStarStarStar
the package works really great.
13 years ago (Manuela von der Decken)
80%StarStarStarStarStar
Does exactly what it says it does, nice example showing it in...
15 years ago (Michael A. Peters)
80%StarStarStarStarStar