ReadMe.txt — Broken Link Checker 1.9.3

broken-link-checker / idn / ReadMe.txt

broken-link-checker / idn Last commit date

LICENCE 15 years ago ReadMe.txt 15 years ago idna_convert.class.php 12 years ago transcode_wrapper.php 12 years ago uctc.php 12 years ago

ReadMe.txt

150 lines

1	*******************************************************************************
2	* *
3	* IDNA Convert (idna_convert.class.php) *
4	* *
5	* http://idnaconv.phlymail.de mailto:phlymail@phlylabs.de *
6	*******************************************************************************
7	* (c) 2004-2008 phlyLabs, Berlin *
8	* This file is encoded in UTF-8 *
9	*******************************************************************************
10
11	Introduction
12	------------
13
14	The class idna_convert allows to convert internationalized domain names
15	(see RFC 3490, 3491, 3492 and 3454 for detials) as they can be used with various
16	registries worldwide to be translated between their original (localized) form
17	and their encoded form as it will be used in the DNS (Domain Name System).
18
19	The class provides two public methods, encode() and decode(), which do exactly
20	what you would expect them to do. You are allowed to use complete domain names,
21	simple strings and complete email addresses as well. That means, that you might
22	use any of the following notations:
23
24	- www.nörgler.com
25	- xn--nrgler-wxa
26	- xn--brse-5qa.xn--knrz-1ra.info
27
28	Errors, incorrectly encoded or invalid strings will lead to either a FALSE
29	response (when in strict mode) or to only partially converted strings.
30	You can query the occured error by calling the method get_last_error().
31
32	Unicode strings are expected to be either UTF-8 strings, UCS-4 strings or UCS-4
33	arrays. The default format is UTF-8. For setting different encodings, you can
34	call the method setParams() - please see the inline documentation for details.
35	ACE strings (the Punycode form) are always 7bit ASCII strings.
36
37	ATTENTION: As of version 0.6.0 of this class it is written in the OOP style of PHP5.
38	Since PHP4 is no longer actively maintained, you should switch to PHP5 as fast as
39	possible.
40	We expect to see no compatibility issues with the upcoming PHP6, too.
41
42
43	Files
44	-----
45	idna_convert.class.php - The actual class
46	example.php - An example web page for converting
47	transcode_wrapper.php - Convert various encodings, see below
48	uctc.php - phlyLabs' Unicode Transcoder, see below
49	ReadMe.txt - This file
50	LICENCE - The LGPL licence file
51
52	The class is contained in idna_convert.class.php.
53
54
55	Examples
56	--------
57	1. Say we wish to encode the domain name nörgler.com:
58
59	// Include the class
60	require_once('idna_convert.class.php');
61	// Instantiate it *
62	$IDN = new idna_convert();
63	// The input string, if input is not UTF-8 or UCS-4, it must be converted before
64	$input = utf8_encode('nörgler.com');
65	// Encode it to its punycode presentation
66	$output = $IDN->encode($input);
67	// Output, what we got now
68	echo $output; // This will read: xn--nrgler-wxa.com
69
70
71	2. We received an email from a punycoded domain and are willing to learn, how
72	the domain name reads originally
73
74	// Include the class
75	require_once('idna_convert.class.php');
76	// Instantiate it (depending on the version you are using) with
77	$IDN = new idna_convert();
78	// The input string
79	$input = 'andre@xn--brse-5qa.xn--knrz-1ra.info';
80	// Encode it to its punycode presentation
81	$output = $IDN->decode($input);
82	// Output, what we got now, if output should be in a format different to UTF-8
83	// or UCS-4, you will have to convert it before outputting it
84	echo utf8_decode($output); // This will read: andre@börse.knörz.info
85
86
87	3. The input is read from a UCS-4 coded file and encoded line by line. By
88	appending the optional second parameter we tell enode() about the input
89	format to be used
90
91	// Include the class
92	require_once('idna_convert.class.php');
93	// Instantiate it
94	$IDN = new dinca_convert();
95	// Iterate through the input file line by line
96	foreach (file('ucs4-domains.txt') as $line) {
97	echo $IDN->encode(trim($line), 'ucs4_string');
98	echo "\n";
99	}
100
101
102	Transcode wrapper
103	-----------------
104	In case you have strings in different encoding than ISO-8859-1 and UTF-8 you might need to
105	translate these strings to UTF-8 before feeding the IDNA converter with it.
106	PHP's built in functions utf8_encode() and utf8_decode() can only deal with ISO-8859-1.
107	Use the file transcode_wrapper.php for the conversion. It requires either iconv, libiconv
108	or mbstring installed together with one of the relevant PHP extensions.
109	The functions you will find useful are
110	encode_utf8() as a replacement for utf8_encode() and
111	decode_utf8() as a replacement for utf8_decode().
112
113	Example usage:
114	<?php
115	require_once('idna_convert.class.php');
116	require_once('transcode_wrapper.php');
117	$mystring = '<something in e.g. ISO-8859-15';
118	$mystring = encode_utf8($mystring, 'ISO-8859-15');
119	echo $IDN->encode($mystring);
120	?>
121
122
123	UCTC - Unicode Transcoder
124	-------------------------
125	Another class you might find useful when dealing with one or more of the Unicode encoding
126	flavours. The class is static, it requires PHP5. It can transcode into each other:
127	- UCS-4 string / array
128	- UTF-8
129	- UTF-7
130	- UTF-7 IMAP (modified UTF-7)
131	All encodings expect / return a string in the given format, with one major exception:
132	UCS-4 array is jsut an array, where each value represents one codepoint in the string, i.e.
133	every value is a 32bit integer value.
134
135	Example usage:
136	<?php
137	require_once('uctc.php');
138	$mystring = 'nörgler.com';
139	echo uctc::convert($mystring, 'utf8', 'utf7imap');
140	?>
141
142
143	Contact us
144	----------
145	In case of errors, bugs, questions, wishes, please don't hesitate to contact us
146	under the email address above.
147
148	The team of phlyLabs
149	http://phlylabs.de
150	mailto:phlymail@phlylabs.de