Explicitly initialize anonModule to null.
[htmlpurifier.git] / docs / enduser-utf8.html
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"><head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="description" content="Describes the rationale for using UTF-8, the ramifications otherwise, and how to make the switch." />
7 <link rel="stylesheet" type="text/css" href="./style.css" />
8 <style type="text/css">
9 .minor td {font-style:italic;}
10 </style>
12 <title>UTF-8: The Secret of Character Encoding - HTML Purifier</title>
14 <!-- Note to users: this document, though professing to be UTF-8, attempts
15 to use only ASCII characters, because most webservers are configured
16 to send HTML as ISO-8859-1. So I will, many times, go against my
17 own advice for sake of portability. -->
19 </head><body>
21 <h1>UTF-8: The Secret of Character Encoding</h1>
23 <div id="filing">Filed under End-User</div>
24 <div id="index">Return to the <a href="index.html">index</a>.</div>
25 <div id="home"><a href="http://htmlpurifier.org/">HTML Purifier</a> End-User Documentation</div>
27 <p>Character encoding and character sets are not that
28 difficult to understand, but so many people blithely stumble
29 through the worlds of programming without knowing what to actually
30 do about it, or say &quot;Ah, it's a job for those <em>internationalization</em>
31 experts.&quot; No, it is not! This document will walk you through
32 determining the encoding of your system and how you should handle
33 this information. It will stay away from excessive discussion on
34 the internals of character encoding.</p>
36 <p>This document is not designed to be read in its entirety: it will
37 slowly introduce concepts that build on each other: you need not get to
38 the bottom to have learned something new. However, I strongly
39 recommend you read all the way to <strong>Why UTF-8?</strong>, because at least
40 at that point you'd have made a conscious decision not to migrate,
41 which can be a rewarding (but difficult) task.</p>
43 <blockquote class="aside">
44 <div class="label">Asides</div>
45 <p>Text in this formatting is an <strong>aside</strong>,
46 interesting tidbits for the curious but not strictly necessary material to
47 do the tutorial. If you read this text, you'll come out
48 with a greater understanding of the underlying issues.</p>
49 </blockquote>
51 <h2>Table of Contents</h2>
53 <ol id="toc">
54 <li><a href="#findcharset">Finding the real encoding</a></li>
55 <li><a href="#findmetacharset">Finding the embedded encoding</a></li>
56 <li><a href="#fixcharset">Fixing the encoding</a><ol>
57 <li><a href="#fixcharset-none">No embedded encoding</a></li>
58 <li><a href="#fixcharset-diff">Embedded encoding disagrees</a></li>
59 <li><a href="#fixcharset-server">Changing the server encoding</a><ol>
60 <li><a href="#fixcharset-server-php">PHP header() function</a></li>
61 <li><a href="#fixcharset-server-phpini">PHP ini directive</a></li>
62 <li><a href="#fixcharset-server-nophp">Non-PHP</a></li>
63 <li><a href="#fixcharset-server-htaccess">.htaccess</a></li>
64 <li><a href="#fixcharset-server-ext">File extensions</a></li>
65 </ol></li>
66 <li><a href="#fixcharset-xml">XML</a></li>
67 <li><a href="#fixcharset-internals">Inside the process</a></li>
68 </ol></li>
69 <li><a href="#whyutf8">Why UTF-8?</a><ol>
70 <li><a href="#whyutf8-i18n">Internationalization</a></li>
71 <li><a href="#whyutf8-user">User-friendly</a></li>
72 <li><a href="#whyutf8-forms">Forms</a><ol>
73 <li><a href="#whyutf8-forms-urlencoded">application/x-www-form-urlencoded</a></li>
74 <li><a href="#whyutf8-forms-multipart">multipart/form-data</a></li>
75 </ol></li>
76 <li><a href="#whyutf8-support">Well supported</a></li>
77 <li><a href="#whyutf8-htmlpurifier">HTML Purifiers</a></li>
78 </ol></li>
79 <li><a href="#migrate">Migrate to UTF-8</a><ol>
80 <li><a href="#migrate-db">Configuring your database</a><ol>
81 <li><a href="#migrate-db-legit">Legit method</a></li>
82 <li><a href="#migrate-db-binary">Binary</a></li>
83 </ol></li>
84 <li><a href="#migrate-editor">Text editor</a></li>
85 <li><a href="#migrate-bom">Byte Order Mark (headers already sent!)</a></li>
86 <li><a href="#migrate-fonts">Fonts</a><ol>
87 <li><a href="#migrate-fonts-obscure">Obscure scripts</a></li>
88 <li><a href="#migrate-fonts-occasional">Occasional use</a></li>
89 </ol></li>
90 <li><a href="#migrate-variablewidth">Dealing with variable width in functions</a></li>
91 </ol></li>
92 <li><a href="#externallinks">Further Reading</a></li>
93 </ol>
95 <h2 id="findcharset">Finding the real encoding</h2>
97 <p>In the beginning, there was ASCII, and things were simple. But they
98 weren't good, for no one could write in Cyrillic or Thai. So there
99 exploded a proliferation of character encodings to remedy the problem
100 by extending the characters ASCII could express. This ridiculously
101 simplified version of the history of character encodings shows us that
102 there are now many character encodings floating around.</p>
104 <blockquote class="aside">
105 <p>A <strong>character encoding</strong> tells the computer how to
106 interpret raw zeroes and ones into real characters. It
107 usually does this by pairing numbers with characters.</p>
108 <p>There are many different types of character encodings floating
109 around, but the ones we deal most frequently with are ASCII,
110 8-bit encodings, and Unicode-based encodings.</p>
111 <ul>
112 <li><strong>ASCII</strong> is a 7-bit encoding based on the
113 English alphabet.</li>
114 <li><strong>8-bit encodings</strong> are extensions to ASCII
115 that add a potpourri of useful, non-standard characters
116 like &eacute; and &aelig;. They can only add 127 characters,
117 so usually only support one script at a time. When you
118 see a page on the web, chances are it's encoded in one
119 of these encodings.</li>
120 <li><strong>Unicode-based encodings</strong> implement the
121 Unicode standard and include UTF-8, UTF-16 and UTF-32/UCS-4.
122 They go beyond 8-bits and support almost
123 every language in the world. UTF-8 is gaining traction
124 as the dominant international encoding of the web.</li>
125 </ul>
126 </blockquote>
128 <p>The first step of our journey is to find out what the encoding of
129 your website is. The most reliable way is to ask your
130 browser:</p>
132 <dl>
133 <dt>Mozilla Firefox</dt>
134 <dd>Tools &gt; Page Info: Encoding</dd>
135 <dt>Internet Explorer</dt>
136 <dd>View &gt; Encoding: bulleted item is unofficial name</dd>
137 </dl>
139 <p>Internet Explorer won't give you the MIME (i.e. useful/real) name of the
140 character encoding, so you'll have to look it up using their description.
141 Some common ones:</p>
143 <table class="table">
144 <thead><tr>
145 <th>IE's Description</th>
146 <th>Mime Name</th>
147 </tr></thead>
148 <tbody>
149 <tr><th colspan="2">Windows</th></tr>
150 <tr><td>Arabic (Windows)</td><td>Windows-1256</td></tr>
151 <tr><td>Baltic (Windows)</td><td>Windows-1257</td></tr>
152 <tr><td>Central European (Windows)</td><td>Windows-1250</td></tr>
153 <tr><td>Cyrillic (Windows)</td><td>Windows-1251</td></tr>
154 <tr><td>Greek (Windows)</td><td>Windows-1253</td></tr>
155 <tr><td>Hebrew (Windows)</td><td>Windows-1255</td></tr>
156 <tr><td>Thai (Windows)</td><td>TIS-620</td></tr>
157 <tr><td>Turkish (Windows)</td><td>Windows-1254</td></tr>
158 <tr><td>Vietnamese (Windows)</td><td>Windows-1258</td></tr>
159 <tr><td>Western European (Windows)</td><td>Windows-1252</td></tr>
160 </tbody>
161 <tbody>
162 <tr><th colspan="2">ISO</th></tr>
163 <tr><td>Arabic (ISO)</td><td>ISO-8859-6</td></tr>
164 <tr><td>Baltic (ISO)</td><td>ISO-8859-4</td></tr>
165 <tr><td>Central European (ISO)</td><td>ISO-8859-2</td></tr>
166 <tr><td>Cyrillic (ISO)</td><td>ISO-8859-5</td></tr>
167 <tr class="minor"><td>Estonian (ISO)</td><td>ISO-8859-13</td></tr>
168 <tr class="minor"><td>Greek (ISO)</td><td>ISO-8859-7</td></tr>
169 <tr><td>Hebrew (ISO-Logical)</td><td>ISO-8859-8-l</td></tr>
170 <tr><td>Hebrew (ISO-Visual)</td><td>ISO-8859-8</td></tr>
171 <tr class="minor"><td>Latin 9 (ISO)</td><td>ISO-8859-15</td></tr>
172 <tr class="minor"><td>Turkish (ISO)</td><td>ISO-8859-9</td></tr>
173 <tr><td>Western European (ISO)</td><td>ISO-8859-1</td></tr>
174 </tbody>
175 <tbody>
176 <tr><th colspan="2">Other</th></tr>
177 <tr><td>Chinese Simplified (GB18030)</td><td>GB18030</td></tr>
178 <tr><td>Chinese Simplified (GB2312)</td><td>GB2312</td></tr>
179 <tr><td>Chinese Simplified (HZ)</td><td>HZ</td></tr>
180 <tr><td>Chinese Traditional (Big5)</td><td>Big5</td></tr>
181 <tr><td>Japanese (Shift-JIS)</td><td>Shift_JIS</td></tr>
182 <tr><td>Japanese (EUC)</td><td>EUC-JP</td></tr>
183 <tr><td>Korean</td><td>EUC-KR</td></tr>
184 <tr><td>Unicode (UTF-8)</td><td>UTF-8</td></tr>
185 </tbody>
186 </table>
188 <p>Internet Explorer does not recognize some of the more obscure
189 character encodings, and having to lookup the real names with a table
190 is a pain, so I recommend using Mozilla Firefox to find out your
191 character encoding.</p>
193 <h2 id="findmetacharset">Finding the embedded encoding</h2>
195 <p>At this point, you may be asking, &quot;Didn't we already find out our
196 encoding?&quot; Well, as it turns out, there are multiple places where
197 a web developer can specify a character encoding, and one such place
198 is in a <code>META</code> tag:</p>
200 <pre>&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=UTF-8&quot; /&gt;</pre>
202 <p>You'll find this in the <code>HEAD</code> section of an HTML document.
203 The text to the right of <code>charset=</code> is the &quot;claimed&quot;
204 encoding: the HTML claims to be this encoding, but whether or not this
205 is actually the case depends on other factors. For now, take note
206 if your <code>META</code> tag claims that either:</p>
208 <ol>
209 <li>The character encoding is the same as the one reported by the
210 browser,</li>
211 <li>The character encoding is different from the browser's, or</li>
212 <li>There is no <code>META</code> tag at all! (horror, horror!)</li>
213 </ol>
215 <h2 id="fixcharset">Fixing the encoding</h2>
217 <p class="aside">The advice given here is for pages being served as
218 vanilla <code>text/html</code>. Different practices must be used
219 for <code>application/xml</code> or <code>application/xml+xhtml</code>, see
220 <a href="http://www.w3.org/TR/2002/NOTE-xhtml-media-types-20020430/">W3C's
221 document on XHTML media types</a> for more information.</p>
223 <p>If your <code>META</code> encoding and your real encoding match,
224 savvy! You can skip this section. If they don't...</p>
226 <h3 id="fixcharset-none">No embedded encoding</h3>
228 <p>If this is the case, you'll want to add in the appropriate
229 <code>META</code> tag to your website. It's as simple as copy-pasting
230 the code snippet above and replacing UTF-8 with whatever is the mime name
231 of your real encoding.</p>
233 <blockquote class="aside">
234 <p>For all those skeptics out there, there is a very good reason
235 why the character encoding should be explicitly stated. When the
236 browser isn't told what the character encoding of a text is, it
237 has to guess: and sometimes the guess is wrong. Hackers can manipulate
238 this guess in order to slip XSS past filters and then fool the
239 browser into executing it as active code. A great example of this
240 is the <a href="http://shiflett.org/archive/177">Google UTF-7
241 exploit</a>.</p>
242 <p>You might be able to get away with not specifying a character
243 encoding with the <code>META</code> tag as long as your webserver
244 sends the right Content-Type header, but why risk it? Besides, if
245 the user downloads the HTML file, there is no longer any webserver
246 to define the character encoding.</p>
247 </blockquote>
249 <h3 id="fixcharset-diff">Embedded encoding disagrees</h3>
251 <p>This is an extremely common mistake: another source is telling
252 the browser what the
253 character encoding is and is overriding the embedded encoding. This
254 source usually is the Content-Type HTTP header that the webserver (i.e.
255 Apache) sends. A usual Content-Type header sent with a page might
256 look like this:</p>
258 <pre>Content-Type: text/html; charset=ISO-8859-1</pre>
260 <p>Notice how there is a charset parameter: this is the webserver's
261 way of telling a browser what the character encoding is, much like
262 the <code>META</code> tags we touched upon previously.</p>
264 <blockquote class="aside"><p>In fact, the <code>META</code> tag is
265 designed as a substitute for the HTTP header for contexts where
266 sending headers is impossible (such as locally stored files without
267 a webserver). Thus the name <code>http-equiv</code> (HTTP equivalent).
268 </p></blockquote>
270 <p>There are two ways to go about fixing this: changing the <code>META</code>
271 tag to match the HTTP header, or changing the HTTP header to match
272 the <code>META</code> tag. How do we know which to do? It depends
273 on the website's content: after all, headers and tags are only ways of
274 describing the actual characters on the web page.</p>
276 <p>If your website:</p>
278 <dl>
279 <dt>...only uses ASCII characters,</dt>
280 <dd>Either way is fine, but I recommend switching both to
281 UTF-8 (more on this later).</dd>
282 <dt>...uses special characters, and they display
283 properly,</dt>
284 <dd>Change the embedded encoding to the server encoding.</dd>
285 <dt>...uses special characters, but users often complain that
286 they come out garbled,</dt>
287 <dd>Change the server encoding to the embedded encoding.</dd>
288 </dl>
290 <p>Changing a META tag is easy: just swap out the old encoding
291 for the new. Changing the server (HTTP header) encoding, however,
292 is slightly more difficult.</p>
294 <h3 id="fixcharset-server">Changing the server encoding</h3>
296 <h4 id="fixcharset-server-php">PHP header() function</h4>
298 <p>The simplest way to handle this problem is to send the encoding
299 yourself, via your programming language. Since you're using HTML
300 Purifier, I'll assume PHP, although it's not too difficult to do
301 similar things in
302 <a href="http://www.w3.org/International/O-HTTP-charset#scripting">other
303 languages</a>. The appropriate code is:</p>
305 <pre><a href="http://php.net/function.header">header</a>('Content-Type:text/html; charset=UTF-8');</pre>
307 <p>...replacing UTF-8 with whatever your embedded encoding is.
308 This code must come before any output, so be careful about
309 stray whitespace in your application (i.e., any whitespace before
310 output excluding whitespace within &lt;?php ?&gt; tags).</p>
312 <h4 id="fixcharset-server-phpini">PHP ini directive</h4>
314 <p>PHP also has a neat little ini directive that can save you a
315 header call: <code><a href="http://php.net/ini.core#ini.default-charset">default_charset</a></code>. Using this code:</p>
317 <pre><a href="http://php.net/function.ini_set">ini_set</a>('default_charset', 'UTF-8');</pre>
319 <p>...will also do the trick. If PHP is running as an Apache module (and
320 not as FastCGI, consult
321 <a href="http://php.net/phpinfo">phpinfo</a>() for details), you can even use htaccess to apply this property
322 across many PHP files:</p>
324 <pre><a href="http://php.net/configuration.changes#configuration.changes.apache">php_value</a> default_charset &quot;UTF-8&quot;</pre>
326 <blockquote class="aside"><p>As with all INI directives, this can
327 also go in your php.ini file. Some hosting providers allow you to customize
328 your own php.ini file, ask your support for details. Use:</p>
329 <pre>default_charset = &quot;utf-8&quot;</pre></blockquote>
331 <h4 id="fixcharset-server-nophp">Non-PHP</h4>
333 <p>You may, for whatever reason, need to set the character encoding
334 on non-PHP files, usually plain ol' HTML files. Doing this
335 is more of a hit-or-miss process: depending on the software being
336 used as a webserver and the configuration of that software, certain
337 techniques may work, or may not work.</p>
339 <h4 id="fixcharset-server-htaccess">.htaccess</h4>
341 <p>On Apache, you can use an .htaccess file to change the character
342 encoding. I'll defer to
343 <a href="http://www.w3.org/International/questions/qa-htaccess-charset">W3C</a>
344 for the in-depth explanation, but it boils down to creating a file
345 named .htaccess with the contents:</p>
347 <pre><a href="http://httpd.apache.org/docs/1.3/mod/mod_mime.html#addcharset">AddCharset</a> UTF-8 .html</pre>
349 <p>Where UTF-8 is replaced with the character encoding you want to
350 use and .html is a file extension that this will be applied to. This
351 character encoding will then be set for any file directly in
352 or in the subdirectories of directory you place this file in.</p>
354 <p>If you're feeling particularly courageous, you can use:</p>
356 <pre><a href="http://httpd.apache.org/docs/1.3/mod/core.html#adddefaultcharset">AddDefaultCharset</a> UTF-8</pre>
358 <p>...which changes the character set Apache adds to any document that
359 doesn't have any Content-Type parameters. This directive, which the
360 default configuration file sets to iso-8859-1 for security
361 reasons, is probably why your headers mismatch
362 with the <code>META</code> tag. If you would prefer Apache not to be
363 butting in on your character encodings, you can tell it not
364 to send anything at all:</p>
366 <pre><a href="http://httpd.apache.org/docs/1.3/mod/core.html#adddefaultcharset">AddDefaultCharset</a> Off</pre>
368 <p>...making your internal charset declaration (usually the <code>META</code> tags)
369 the sole source of character encoding
370 information. In these cases, it is <em>especially</em> important to make
371 sure you have valid <code>META</code> tags on your pages and all the
372 text before them is ASCII.</p>
374 <blockquote class="aside"><p>These directives can also be
375 placed in httpd.conf file for Apache, but
376 in most shared hosting situations you won't be able to edit this file.
377 </p></blockquote>
379 <h4 id="fixcharset-server-ext">File extensions</h4>
381 <p>If you're not allowed to use .htaccess files, you can often
382 piggy-back off of Apache's default AddCharset declarations to get
383 your files in the proper extension. Here are Apache's default
384 character set declarations:</p>
386 <table class="table">
387 <thead><tr>
388 <th>Charset</th>
389 <th>File extension(s)</th>
390 </tr></thead>
391 <tbody>
392 <tr><td>ISO-8859-1</td><td>.iso8859-1 .latin1</td></tr>
393 <tr><td>ISO-8859-2</td><td>.iso8859-2 .latin2 .cen</td></tr>
394 <tr><td>ISO-8859-3</td><td>.iso8859-3 .latin3</td></tr>
395 <tr><td>ISO-8859-4</td><td>.iso8859-4 .latin4</td></tr>
396 <tr><td>ISO-8859-5</td><td>.iso8859-5 .latin5 .cyr .iso-ru</td></tr>
397 <tr><td>ISO-8859-6</td><td>.iso8859-6 .latin6 .arb</td></tr>
398 <tr><td>ISO-8859-7</td><td>.iso8859-7 .latin7 .grk</td></tr>
399 <tr><td>ISO-8859-8</td><td>.iso8859-8 .latin8 .heb</td></tr>
400 <tr><td>ISO-8859-9</td><td>.iso8859-9 .latin9 .trk</td></tr>
401 <tr><td>ISO-2022-JP</td><td>.iso2022-jp .jis</td></tr>
402 <tr><td>ISO-2022-KR</td><td>.iso2022-kr .kis</td></tr>
403 <tr><td>ISO-2022-CN</td><td>.iso2022-cn .cis</td></tr>
404 <tr><td>Big5</td><td>.Big5 .big5 .b5</td></tr>
405 <tr><td>WINDOWS-1251</td><td>.cp-1251 .win-1251</td></tr>
406 <tr><td>CP866</td><td>.cp866</td></tr>
407 <tr><td>KOI8-r</td><td>.koi8-r .koi8-ru</td></tr>
408 <tr><td>KOI8-ru</td><td>.koi8-uk .ua</td></tr>
409 <tr><td>ISO-10646-UCS-2</td><td>.ucs2</td></tr>
410 <tr><td>ISO-10646-UCS-4</td><td>.ucs4</td></tr>
411 <tr><td>UTF-8</td><td>.utf8</td></tr>
412 <tr><td>GB2312</td><td>.gb2312 .gb </td></tr>
413 <tr><td>utf-7</td><td>.utf7</td></tr>
414 <tr><td>EUC-TW</td><td>.euc-tw</td></tr>
415 <tr><td>EUC-JP</td><td>.euc-jp</td></tr>
416 <tr><td>EUC-KR</td><td>.euc-kr</td></tr>
417 <tr><td>shift_jis</td><td>.sjis</td></tr>
418 </tbody>
419 </table>
421 <p>So, for example, a file named <code>page.utf8.html</code> or
422 <code>page.html.utf8</code> will probably be sent with the UTF-8 charset
423 attached, the difference being that if there is an
424 <code>AddCharset charset .html</code> declaration, it will override
425 the .utf8 extension in <code>page.utf8.html</code> (precedence moves
426 from right to left). By default, Apache has no such declaration.</p>
428 <h4 id="fixcharset-server-iis">Microsoft IIS</h4>
430 <p>If anyone can contribute information on how to configure Microsoft
431 IIS to change character encodings, I'd be grateful.</p>
433 <h3 id="fixcharset-xml">XML</h3>
435 <p><code>META</code> tags are the most common source of embedded
436 encodings, but they can also come from somewhere else: XML
437 Declarations. They look like:</p>
439 <pre>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</pre>
441 <p>...and are most often found in XML documents (including XHTML).</p>
443 <p>For XHTML, this XML Declaration theoretically
444 overrides the <code>META</code> tag. In reality, this happens only when the
445 XHTML is actually served as legit XML and not HTML, which is almost always
446 never due to Internet Explorer's lack of support for
447 <code>application/xhtml+xml</code> (even though doing so is often
448 argued to be <a href="http://www.hixie.ch/advocacy/xhtml">good
449 practice</a> and is required by the XHTML 1.1 specification).</p>
451 <p>For XML, however, this XML Declaration is extremely important.
452 Since most webservers are not configured to send charsets for .xml files,
453 this is the only thing a parser has to go on. Furthermore, the default
454 for XML files is UTF-8, which often butts heads with more common
455 ISO-8859-1 encoding (you see this in garbled RSS feeds).</p>
457 <p>In short, if you use XHTML and have gone through the
458 trouble of adding the XML Declaration, make sure it jives
459 with your <code>META</code> tags (which should only be present
460 if served in text/html) and HTTP headers.</p>
462 <h3 id="fixcharset-internals">Inside the process</h3>
464 <p>This section is not required reading,
465 but may answer some of your questions on what's going on in all
466 this character encoding hocus pocus. If you're interested in
467 moving on to the next phase, skip this section.</p>
469 <p>A logical question that follows all of our wheeling and dealing
470 with multiple sources of character encodings is &quot;Why are there
471 so many options?&quot; To answer this question, we have to turn
472 back our definition of character encodings: they allow a program
473 to interpret bytes into human-readable characters.</p>
475 <p>Thus, a chicken-egg problem: a character encoding
476 is necessary to interpret the
477 text of a document. A <code>META</code> tag is in the text of a document.
478 The <code>META</code> tag gives the character encoding. How can we
479 determine the contents of a <code>META</code> tag, inside the text,
480 if we don't know it's character encoding? And how do we figure out
481 the character encoding, if we don't know the contents of the
482 <code>META</code> tag?</p>
484 <p>Fortunately for us, the characters we need to write the
485 <code>META</code> are in ASCII, which is pretty much universal
486 over every character encoding that is in common use today. So,
487 all the web-browser has to do is parse all the way down until
488 it gets to the Content-Type tag, extract the character encoding
489 tag, then re-parse the document according to this new information.</p>
491 <p>Obviously this is complicated, so browsers prefer the simpler
492 and more efficient solution: get the character encoding from a
493 somewhere other than the document itself, i.e. the HTTP headers,
494 much to the chagrin of HTML authors who can't set these headers.</p>
496 <h2 id="whyutf8">Why UTF-8?</h2>
498 <p>So, you've gone through all the trouble of ensuring that your
499 server and embedded characters all line up properly and are
500 present. Good job: at
501 this point, you could quit and rest easy knowing that your pages
502 are not vulnerable to character encoding style XSS attacks.
503 However, just as having a character encoding is better than
504 having no character encoding at all, having UTF-8 as your
505 character encoding is better than having some other random
506 character encoding, and the next step is to convert to UTF-8.
507 But why?</p>
509 <h3 id="whyutf8-i18n">Internationalization</h3>
511 <p>Many software projects, at one point or another, suddenly realize
512 that they should be supporting more than one language. Even regular
513 usage in one language sometimes requires the occasional special character
514 that, without surprise, is not available in your character set. Sometimes
515 developers get around this by adding support for multiple encodings: when
516 using Chinese, use Big5, when using Japanese, use Shift-JIS, when
517 using Greek, etc. Other times, they use character references with great
518 zeal.</p>
520 <p>UTF-8, however, obviates the need for any of these complicated
521 measures. After getting the system to use UTF-8 and adjusting for
522 sources that are outside the hand of the browser (more on this later),
523 UTF-8 just works. You can use it for any language, even many languages
524 at once, you don't have to worry about managing multiple encodings,
525 you don't have to use those user-unfriendly entities.</p>
527 <h3 id="whyutf8-user">User-friendly</h3>
529 <p>Websites encoded in Latin-1 (ISO-8859-1) which occasionally need
530 a special character outside of their scope often will use a character
531 entity reference to achieve the desired effect. For instance, &theta; can be
532 written <code>&amp;theta;</code>, regardless of the character encoding's
533 support of Greek letters.</p>
535 <p>This works nicely for limited use of special characters, but
536 say you wanted this sentence of Chinese text: &#28608;&#20809;,
537 &#36889;&#20841;&#20491;&#23383;&#26159;&#29978;&#40636;&#24847;&#24605;.
538 The ampersand encoded version would look like this:</p>
540 <pre>&amp;#28608;&amp;#20809;, &amp;#36889;&amp;#20841;&amp;#20491;&amp;#23383;&amp;#26159;&amp;#29978;&amp;#40636;&amp;#24847;&amp;#24605;</pre>
542 <p>Extremely inconvenient for those of us who actually know what
543 character entities are, totally unintelligible to poor users who don't!
544 Even the slightly more user-friendly, &quot;intelligible&quot; character
545 entities like <code>&amp;theta;</code> will leave users who are
546 uninterested in learning HTML scratching their heads. On the other
547 hand, if they see &theta; in an edit box, they'll know that it's a
548 special character, and treat it accordingly, even if they don't know
549 how to write that character themselves.</p>
551 <blockquote class="aside"><p>Wikipedia is a great case study for
552 an application that originally used ISO-8859-1 but switched to UTF-8
553 when it became far to cumbersome to support foreign languages. Bots
554 will now actually go through articles and convert character entities
555 to their corresponding real characters for the sake of user-friendliness
556 and searchability. See
557 <a href="http://meta.wikimedia.org/wiki/Help:Special_characters">Meta's
558 page on special characters</a> for more details.
559 </p></blockquote>
561 <h3 id="whyutf8-forms">Forms</h3>
563 <p>While we're on the tack of users, how do non-UTF-8 web forms deal
564 with characters that our outside of their character set? Rather than
565 discuss what UTF-8 does right, we're going to show what could go wrong
566 if you didn't use UTF-8 and people tried to use characters outside
567 of your character encoding.</p>
569 <p>The troubles are large, extensive, and extremely difficult to fix (or,
570 at least, difficult enough that if you had the time and resources to invest
571 in doing the fix, you would be probably better off migrating to UTF-8).
572 There are two types of form submission: <code>application/x-www-form-urlencoded</code>
573 which is used for GET and by default for POST, and <code>multipart/form-data</code>
574 which may be used by POST, and is required when you want to upload
575 files.</p>
577 <p>The following is a summarization of notes from
578 <a href="http://web.archive.org/web/20060427015200/ppewww.ph.gla.ac.uk/~flavell/charset/form-i18n.html">
579 <code>FORM</code> submission and i18n</a>. That document contains lots
580 of useful information, but is written in a rambly manner, so
581 here I try to get right to the point. (Note: the original has
582 disappeared off the web, so I am linking to the Web Archive copy.)</p>
584 <h4 id="whyutf8-forms-urlencoded"><code>application/x-www-form-urlencoded</code></h4>
586 <p>This is the Content-Type that GET requests must use, and POST requests
587 use by default. It involves the ubiquitous percent encoding format that
588 looks something like: <code>%C3%86</code>. There is no official way of
589 determining the character encoding of such a request, since the percent
590 encoding operates on a byte level, so it is usually assumed that it
591 is the same as the encoding the page containing the form was submitted
592 in. (<a href="http://tools.ietf.org/html/rfc3986#section-2.5">RFC 3986</a>
593 recommends that textual identifiers be translated to UTF-8; however, browser
594 compliance is spotty.) You'll run into very few problems
595 if you only use characters in the character encoding you chose.</p>
597 <p>However, once you start adding characters outside of your encoding
598 (and this is a lot more common than you may think: take curly
599 &quot;smart&quot; quotes from Microsoft as an example),
600 a whole manner of strange things start to happen. Depending on the
601 browser you're using, they might:</p>
603 <ul>
604 <li>Replace the unsupported characters with useless question marks,</li>
605 <li>Attempt to fix the characters (example: smart quotes to regular quotes),</li>
606 <li>Replace the character with a character entity reference, or</li>
607 <li>Send it anyway as a different character encoding mixed in
608 with the original encoding (usually Windows-1252 rather than
609 iso-8859-1 or UTF-8 interspersed in 8-bit)</li>
610 </ul>
612 <p>To properly guard against these behaviors, you'd have to sniff out
613 the browser agent, compile a database of different behaviors, and
614 take appropriate conversion action against the string (disregarding
615 a spate of extremely mysterious, random and devastating bugs Internet
616 Explorer manifests every once in a while). Or you could
617 use UTF-8 and rest easy knowing that none of this could possibly happen
618 since UTF-8 supports every character.</p>
620 <h4 id="whyutf8-forms-multipart"><code>multipart/form-data</code></h4>
622 <p>Multipart form submission takes away a lot of the ambiguity
623 that percent-encoding had: the server now can explicitly ask for
624 certain encodings, and the client can explicitly tell the server
625 during the form submission what encoding the fields are in.</p>
627 <p>There are two ways you go with this functionality: leave it
628 unset and have the browser send in the same encoding as the page,
629 or set it to UTF-8 and then do another conversion server-side.
630 Each method has deficiencies, especially the former.</p>
632 <p>If you tell the browser to send the form in the same encoding as
633 the page, you still have the trouble of what to do with characters
634 that are outside of the character encoding's range. The behavior, once
635 again, varies: Firefox 2.0 converts them to character entity references
636 while Internet Explorer 7.0 mangles them beyond intelligibility. For
637 serious internationalization purposes, this is not an option.</p>
639 <p>The other possibility is to set Accept-Encoding to UTF-8, which
640 begs the question: Why aren't you using UTF-8 for everything then?
641 This route is more palatable, but there's a notable caveat: your data
642 will come in as UTF-8, so you will have to explicitly convert it into
643 your favored local character encoding.</p>
645 <p>I object to this approach on idealogical grounds: you're
646 digging yourself deeper into
647 the hole when you could have been converting to UTF-8
648 instead. And, of course, you can't use this method for GET requests.</p>
650 <h3 id="whyutf8-support">Well supported</h3>
652 <p>Almost every modern browser in the wild today has full UTF-8 and Unicode
653 support: the number of troublesome cases can be counted with the
654 fingers of one hand, and these browsers usually have trouble with
655 other character encodings too. Problems users usually encounter stem
656 from the lack of appropriate fonts to display the characters (once
657 again, this applies to all character encodings and HTML entities) or
658 Internet Explorer's lack of intelligent font picking (which can be
659 worked around).</p>
661 <p>We will go into more detail about how to deal with edge cases in
662 the browser world in the Migration section, but rest assured that
663 converting to UTF-8, if done correctly, will not result in users
664 hounding you about broken pages.</p>
666 <h3 id="whyutf8-htmlpurifier">HTML Purifier</h3>
668 <p>And finally, we get to HTML Purifier. HTML Purifier is built to
669 deal with UTF-8: any indications otherwise are the result of an
670 encoder that converts text from your preferred encoding to UTF-8, and
671 back again. HTML Purifier never touches anything else, and leaves
672 it up to the module iconv to do the dirty work.</p>
674 <p>This approach, however, is not perfect. iconv is blithely unaware
675 of HTML character entities. HTML Purifier, in order to
676 protect against sophisticated escaping schemes, normalizes all character
677 and numeric entity references before processing the text. This leads to
678 one important ramification:</p>
680 <p><strong>Any character that is not supported by the target character
681 set, regardless of whether or not it is in the form of a character
682 entity reference or a raw character, will be silently ignored.</strong></p>
684 <p>Example of this principle at work: say you have <code>&amp;theta;</code>
685 in your HTML, but the output is in Latin-1 (which, understandably,
686 does not understand Greek), the following process will occur (assuming you've
687 set the encoding correctly using %Core.Encoding):</p>
689 <ul>
690 <li>The <code>Encoder</code> will transform the text from ISO 8859-1 to UTF-8
691 (note that theta is preserved here since it doesn't actually use
692 any non-ASCII characters): <code>&amp;theta;</code></li>
693 <li>The <code>EntityParser</code> will transform all named and numeric
694 character entities to their corresponding raw UTF-8 equivalents:
695 <code>&theta;</code></li>
696 <li>HTML Purifier processes the code: <code>&theta;</code></li>
697 <li>The <code>Encoder</code> now transforms the text back from UTF-8
698 to ISO 8859-1. Since Greek is not supported by ISO 8859-1, it
699 will be either ignored or replaced with a question mark:
700 <code>?</code></li>
701 </ul>
703 <p>This behaviour is quite unsatisfactory. It is a deal-breaker for
704 international applications, and it can be mildly annoying for the provincial
705 soul who occasionally needs a special character. Since 1.4.0, HTML
706 Purifier has provided a slightly more palatable workaround using
707 %Core.EscapeNonASCIICharacters. The process now looks like:</p>
709 <ul>
710 <li>The <code>Encoder</code> transforms encoding to UTF-8: <code>&amp;theta;</code></li>
711 <li>The <code>EntityParser</code> transforms entities: <code>&theta;</code></li>
712 <li>HTML Purifier processes the code: <code>&theta;</code></li>
713 <li>The <code>Encoder</code> replaces all non-ASCII characters
714 with numeric entity reference: <code>&amp;#952;</code></li>
715 <li>For good measure, <code>Encoder</code> transforms encoding back to
716 original (which is strictly unnecessary for 99% of encodings
717 out there): <code>&amp;#952;</code> (remember, it's all ASCII!)</li>
718 </ul>
720 <p>...which means that this is only good for an occasional foray into
721 the land of Unicode characters, and is totally unacceptable for Chinese
722 or Japanese texts. The even bigger kicker is that, supposing the
723 input encoding was actually ISO-8859-7, which <em>does</em> support
724 theta, the character would get converted into a character entity reference
725 anyway! (The Encoder does not discriminate).</p>
727 <p>The current functionality is about where HTML Purifier will be for
728 the rest of eternity. HTML Purifier could attempt to preserve the original
729 form of the character references so that they could be substituted back in, only the
730 DOM extension kills them off irreversibly. HTML Purifier could also attempt
731 to be smart and only convert non-ASCII characters that weren't supported
732 by the target encoding, but that would require reimplementing iconv
733 with HTML awareness, something I will not do.</p>
735 <p>So there: either it's UTF-8 or crippled international support. Your pick! (and I'm
736 not being sarcastic here: some people could care less about other languages).</p>
738 <h2 id="migrate">Migrate to UTF-8</h2>
740 <p>So, you've decided to bite the bullet, and want to migrate to UTF-8.
741 Note that this is not for the faint-hearted, and you should expect
742 the process to take longer than you think it will take.</p>
744 <p>The general idea is that you convert all existing text to UTF-8,
745 and then you set all the headers and META tags we discussed earlier
746 to UTF-8. There are many ways going about doing this: you could
747 write a conversion script that runs through the database and re-encodes
748 everything as UTF-8 or you could do the conversion on the fly when someone
749 reads the page. The details depend on your system, but I will cover
750 some of the more subtle points of migration that may trip you up.</p>
752 <h3 id="migrate-db">Configuring your database</h3>
754 <p>Most modern databases, the most prominent open-source ones being MySQL
755 4.1+ and PostgreSQL, support character encodings. If you're switching
756 to UTF-8, logically speaking, you'd want to make sure your database
757 knows about the change too. There are some caveats though:</p>
759 <h4 id="migrate-db-legit">Legit method</h4>
761 <p>Standardization in terms of SQL syntax for specifying character
762 encodings is notoriously spotty. Refer to your respective database's
763 documentation on how to do this properly.</p>
765 <p>For <a href="http://dev.mysql.com/doc/refman/5.0/en/charset-conversion.html">MySQL</a>, <code>ALTER</code> will magically perform the
766 character encoding conversion for you. However, you have
767 to make sure that the text inside the column is what is says it is:
768 if you had put Shift-JIS in an ISO 8859-1 column, MySQL will irreversibly mangle
769 the text when you try to convert it to UTF-8. You'll have to convert
770 it to a binary field, convert it to a Shift-JIS field (the real encoding),
771 and then finally to UTF-8. Many a website had pages irreversibly mangled
772 because they didn't realize that they'd been deluding themselves about
773 the character encoding all along; don't become the next victim.</p>
775 <p>For <a href="http://www.postgresql.org/docs/8.2/static/multibyte.html">PostgreSQL</a>, there appears to be no direct way to change the
776 encoding of a database (as of 8.2). You will have to dump the data, and then reimport
777 it into a new table. Make sure that your client encoding is set properly:
778 this is how PostgreSQL knows to perform an encoding conversion.</p>
780 <p>Many times, you will be also asked about the &quot;collation&quot; of
781 the new column. Collation is how a DBMS sorts text, like ordering
782 B, C and A into A, B and C (the problem gets surprisingly complicated
783 when you get to languages like Thai and Japanese). If in doubt,
784 going with the default setting is usually a safe bet.</p>
786 <p>Once the conversion is all said and done, you still have to remember
787 to set the client encoding (your encoding) properly on each database
788 connection using <code>SET NAMES</code> (which is standard SQL and is
789 usually supported).</p>
791 <h4 id="migrate-db-binary">Binary</h4>
793 <p>Due to the aforementioned compatibility issues, a more interoperable
794 way of storing UTF-8 text is to stuff it in a binary datatype.
795 <code>CHAR</code> becomes <code>BINARY</code>, <code>VARCHAR</code> becomes
796 <code>VARBINARY</code> and <code>TEXT</code> becomes <code>BLOB</code>.
797 Doing so can save you some huge headaches:</p>
799 <ul>
800 <li>The syntax for binary data types is very portable,</li>
801 <li>MySQL 4.0 has <em>no</em> support for character encodings, so
802 if you want to support it you <em>have</em> to use binary,</li>
803 <li>MySQL, as of 5.1, has no support for four byte UTF-8 characters,
804 which represent characters beyond the basic multilingual
805 plane, and</li>
806 <li>You will never have to worry about your DBMS being too smart
807 and attempting to convert your text when you don't want it to.</li>
808 </ul>
810 <p>MediaWiki, a very prominent international application, uses binary fields
811 for storing their data because of point three.</p>
813 <p>There are drawbacks, of course:</p>
815 <ul>
816 <li>Database tools like PHPMyAdmin won't be able to offer you inline
817 text editing, since it is declared as binary,</li>
818 <li>It's not semantically correct: it's really text not binary
819 (lying to the database),</li>
820 <li>Unless you use the not-very-portable wizardry mentioned above,
821 you have to change the encoding yourself (usually, you'd do
822 it on the fly), and</li>
823 <li>You will not have collation.</li>
824 </ul>
826 <p>Choose based on your circumstances.</p>
828 <h3 id="migrate-editor">Text editor</h3>
830 <p>For more flat-file oriented systems, you will often be tasked with
831 converting reams of existing text and HTML files into UTF-8, as well as
832 making sure that all new files uploaded are properly encoded. Once again,
833 I can only point vaguely in the right direction for converting your
834 existing files: make sure you backup, make sure you use
835 <a href="http://php.net/ref.iconv">iconv</a>(), and
836 make sure you know what the original character encoding of the files
837 is (or are, depending on the tidiness of your system).</p>
839 <p>However, I can proffer more specific advice on the subject of
840 text editors. Many text editors have notoriously spotty Unicode support.
841 To find out how your editor is doing, you can check out <a
842 href="http://www.alanwood.net/unicode/utilities_editors.html">this list</a>
843 or <a href="http://en.wikipedia.org/wiki/Comparison_of_text_editors#Encoding_support">Wikipedia's list.</a>
844 I personally use Notepad++, which works like a charm when it comes to UTF-8.
845 Usually, you will have to <strong>explicitly</strong> tell the editor through some dialogue
846 (usually Save as or Format) what encoding you want it to use. An editor
847 will often offer &quot;Unicode&quot; as a method of saving, which is
848 ambiguous. Make sure you know whether or not they really mean UTF-8
849 or UTF-16 (which is another flavor of Unicode).</p>
851 <p>The two things to look out for are whether or not the editor
852 supports <strong>font mixing</strong> (multiple
853 fonts in one document) and whether or not it adds a <strong>BOM</strong>.
854 Font mixing is important because fonts rarely have support for every
855 language known to mankind: in order to be flexible, an editor must
856 be able to take a little from here and a little from there, otherwise
857 all your Chinese characters will come as nice boxes. We'll discuss
858 BOM below.</p>
860 <h3 id="migrate-bom">Byte Order Mark (headers already sent!)</h3>
862 <p>The BOM, or <a href="http://en.wikipedia.org/wiki/Byte_Order_Mark">Byte
863 Order Mark</a>, is a magical, invisible character placed at
864 the beginning of UTF-8 files to tell people what the encoding is and
865 what the endianness of the text is. It is also unnecessary.</p>
867 <p>Because it's invisible, it often
868 catches people by surprise when it starts doing things it shouldn't
869 be doing. For example, this PHP file:</p>
871 <pre><strong>BOM</strong>&lt;?php
872 header('Location: index.php');
873 ?&gt;</pre>
875 <p>...will fail with the all too familiar <strong>Headers already sent</strong>
876 PHP error. And because the BOM is invisible, this culprit will go unnoticed.
877 My suggestion is to only use ASCII in PHP pages, but if you must, make
878 sure the page is saved WITHOUT the BOM.</p>
880 <blockquote class="aside">
881 <p>The headers the error is referring to are <strong>HTTP headers</strong>,
882 which are sent to the browser before any HTML to tell it various
883 information. The moment any regular text (and yes, a BOM counts as
884 ordinary text) is output, the headers must be sent, and you are
885 not allowed to send anymore. Thus, the error.</p>
886 </blockquote>
888 <p>If you are reading in text files to insert into the middle of another
889 page, it is strongly advised (but not strictly necessary) that you replace out the UTF-8 byte
890 sequence for BOM <code>&quot;\xEF\xBB\xBF&quot;</code> before inserting it in,
891 via:</p>
893 <pre>$text = str_replace(&quot;\xEF\xBB\xBF&quot;, '', $text);</pre>
895 <h3 id="migrate-fonts">Fonts</h3>
897 <p>Generally speaking, people who are having trouble with fonts fall
898 into two categories:</p>
900 <ul>
901 <li>Those who want to
902 use an extremely obscure language for which there is very little
903 support even among native speakers of the language, and</li>
904 <li>Those where the primary language of the text is
905 well-supported but there are occasional characters
906 that aren't supported.</li>
907 </ul>
909 <p>Yes, there's always a chance where an English user happens across
910 a Sinhalese website and doesn't have the right font. But an English user
911 who happens not to have the right fonts probably has no business reading Sinhalese
912 anyway. So we'll deal with the other two edge cases.</p>
914 <h4 id="migrate-fonts-obscure">Obscure scripts</h4>
916 <p>If you run a Bengali website, you may get comments from users who
917 would like to read your website but get heaps of question marks or
918 other meaningless characters. Fixing this problem requires the
919 installation of a font or language pack which is often highly
920 dependent on what the language is. <a href="http://bn.wikipedia.org/wiki/%E0%A6%89%E0%A6%87%E0%A6%95%E0%A6%BF%E0%A6%AA%E0%A7%87%E0%A6%A1%E0%A6%BF%E0%A6%AF%E0%A6%BC%E0%A6%BE:Bangla_script_display_and_input_help">Here is an example</a>
921 of such a help file for the Bengali language; I am sure there are
922 others out there too. You just have to point users to the appropriate
923 help file.</p>
925 <h4 id="migrate-fonts-occasional">Occasional use</h4>
927 <p>A prime example of when you'll see some very obscure Unicode
928 characters embedded in what otherwise would be very bland ASCII are
929 letters of the
930 <a href="http://en.wikipedia.org/wiki/International_Phonetic_Alphabet">International
931 Phonetic Alphabet (IPA)</a>, use to designate pronunciations in a very standard
932 manner (you probably see them all the time in your dictionary). Your
933 average font probably won't have support for all of the IPA characters
934 like &#664; (bilabial click) or &#658; (voiced postalveolar fricative).
935 So what's a poor browser to do? Font mix! Smart browsers like Mozilla Firefox
936 and Internet Explorer 7 will borrow glyphs from other fonts in order
937 to make sure that all the characters display properly.</p>
939 <p>But what happens when the browser isn't smart and happens to be the
940 most widely used browser in the entire world? Microsoft IE 6
941 is not smart enough to borrow from other fonts when a character isn't
942 present, so more often than not you'll be slapped with a nice big &#65533;.
943 To get things to work, MSIE 6 needs a little nudge. You could configure it
944 to use a different font to render the text, but you can achieve the same
945 effect by selectively changing the font for blocks of special characters
946 to known good Unicode fonts.</p>
948 <p>Fortunately, the folks over at Wikipedia have already done all the
949 heavy lifting for you. Get the CSS from the horses mouth here:
950 <a href="http://en.wikipedia.org/wiki/MediaWiki:Common.css">Common.css</a>,
951 and search for &quot;.IPA&quot; There are also a smattering of
952 other classes you can use for other purposes, check out
953 <a href="http://meta.wikimedia.org/wiki/Help:Special_characters#Displaying_Special_Characters">this page</a>
954 for more details. For you lazy ones, this should work:</p>
956 <pre>.Unicode {
957 font-family: Code2000, &quot;TITUS Cyberbit Basic&quot;, &quot;Doulos SIL&quot;,
958 &quot;Chrysanthi Unicode&quot;, &quot;Bitstream Cyberbit&quot;,
959 &quot;Bitstream CyberBase&quot;, Thryomanes, Gentium, GentiumAlt,
960 &quot;Lucida Grande&quot;, &quot;Arial Unicode MS&quot;, &quot;Microsoft Sans Serif&quot;,
961 &quot;Lucida Sans Unicode&quot;;
962 font-family /**/:inherit; /* resets fonts for everyone but IE6 */
963 }</pre>
965 <p>The standard usage goes along the lines of <code>&lt;span class=&quot;Unicode&quot;&gt;Crazy
966 Unicode stuff here&lt;/span&gt;</code>. Characters in the
967 <a href="http://en.wikipedia.org/wiki/Windows_Glyph_List_4">Windows Glyph List</a>
968 usually don't need to be fixed, but for anything else you probably
969 want to play it safe. Unless, of course, you don't care about IE6
970 users.</p>
972 <h3 id="migrate-variablewidth">Dealing with variable width in functions</h3>
974 <p>When people claim that PHP6 will solve all our Unicode problems, they're
975 misinformed. It will not fix any of the aforementioned troubles. It will,
976 however, fix the problem we are about to discuss: processing UTF-8 text
977 in PHP.</p>
979 <p>PHP (as of PHP5) is blithely unaware of the existence of UTF-8 (with a few
980 notable exceptions). Sometimes, this will cause problems, other times,
981 this won't. So far, we've avoided discussing the architecture of
982 UTF-8, so, we must first ask, what is UTF-8? Yes, it supports Unicode,
983 and yes, it is variable width. Other traits:</p>
985 <ul>
986 <li>Every character's byte sequence is unique and will never be found
987 inside the byte sequence of another character,</li>
988 <li>UTF-8 may use up to four bytes to encode a character,</li>
989 <li>UTF-8 text must be checked for well-formedness,</li>
990 <li>Pure ASCII is also valid UTF-8, and</li>
991 <li>Binary sorting will sort UTF-8 in the same order as Unicode.</li>
992 </ul>
994 <p>Each of these traits affect different domains of text processing
995 in different ways. It is beyond the scope of this document to explain
996 what precisely these implications are. PHPWact provides
997 a very good <a href="http://www.phpwact.org/php/i18n/utf-8">reference document</a>
998 on what to expect from each function, although coverage is spotty in
999 some areas. Their more general notes on
1000 <a href="http://www.phpwact.org/php/i18n/charsets">character sets</a>
1001 are also worth looking at for information on UTF-8. Some rules of thumb
1002 when dealing with Unicode text:</p>
1004 <ul>
1005 <li>Do not EVER use functions that:<ul>
1006 <li>...convert case (strtolower, strtoupper, ucfirst, ucwords)</li>
1007 <li>...claim to be case-insensitive (str_ireplace, stristr, strcasecmp)</li>
1008 </ul></li>
1009 <li>Think twice before using functions that:<ul>
1010 <li>...count characters (strlen will return bytes, not characters;
1011 str_split and word_wrap may corrupt)</li>
1012 <li>...convert characters to entity references (UTF-8 doesn't need entities)</li>
1013 <li>...do very complex string processing (*printf)</li>
1014 </ul></li>
1015 </ul>
1017 <p>Note: this list applies to UTF-8 encoded text only: if you have
1018 a string that you are 100% sure is ASCII, be my guest and use
1019 <code>strtolower</code> (HTML Purifier uses this function.)</p>
1021 <p>Regardless, always think in bytes, not characters. If you use strpos()
1022 to find the position of a character, it will be in bytes, but this
1023 usually won't matter since substr() also operates with byte indices!</p>
1025 <p>You'll also need to make sure your UTF-8 is well-formed and will
1026 probably need replacements for some of these functions. I recommend
1027 using Harry Fuecks' <a href="http://phputf8.sourceforge.net/">PHP
1028 UTF-8</a> library, rather than use mb_string directly. HTML Purifier
1029 also defines a few useful UTF-8 compatible functions: check out
1030 <code>Encoder.php</code> in the <code>/library/HTMLPurifier/</code>
1031 directory.</p>
1033 <h2 id="externallinks">Further Reading</h2>
1035 <p>Well, that's it. Hopefully this document has served as a very
1036 practical springboard into knowledge of how UTF-8 works. You may have
1037 decided that you don't want to migrate yet: that's fine, just know
1038 what will happen to your output and what bug reports you may receive.</p>
1040 <p>Many other developers have already discussed the subject of Unicode,
1041 UTF-8 and internationalization, and I would like to defer to them for
1042 a more in-depth look into character sets and encodings.</p>
1044 <ul>
1045 <li><a href="http://www.joelonsoftware.com/articles/Unicode.html">
1046 The Absolute Minimum Every Software Developer Absolutely,
1047 Positively Must Know About Unicode and Character Sets
1048 (No Excuses!)</a> by Joel Spolsky, provides a <em>very</em>
1049 good high-level look at Unicode and character sets in general.</li>
1050 <li><a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8 on Wikipedia</a>,
1051 provides a lot of useful details into the innards of UTF-8, although
1052 it may be a little off-putting to people who don't know much
1053 about Unicode to begin with.</li>
1054 </ul>
1056 </body>
1057 </html>
1059 <!-- vim: et sw=4 sts=4