3 How to install HTML Purifier
5 HTML Purifier is designed to run out of the box, so actually using the
6 library is extremely easy. (Although... if you were looking for a
7 step-by-step installation GUI, you've downloaded the wrong software!)
9 While the impatient can get going immediately with some of the sample
10 code at the bottom of this library, it's well worth reading this entire
11 document--most of the other documentation assumes that you are familiar
15 ---------------------------------------------------------------------------
18 HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.0 and
19 up (see tests/multitest.php for the specific versions that are being
20 tested regularly). It has no core dependencies with other libraries. PHP
21 4 support was deprecated on December 31, 2007 with HTML Purifier 3.0.0.
22 Essential security fixes will be issued for the 2.1.x branch until
25 These optional extensions can enhance the capabilities of HTML Purifier:
27 * iconv : Converts text to and from non-UTF-8 encodings
28 * tidy : Used for pretty-printing HTML
31 ---------------------------------------------------------------------------
34 A big plus of HTML Purifier is its inerrant support of standards, so
35 your web-pages should be standards-compliant. (They should also use
36 semantic markup, but that's another issue altogether, one HTML Purifier
37 cannot fix without reading your mind.)
39 HTML Purifier can process these doctypes:
41 * XHTML 1.0 Transitional (default)
43 * HTML 4.01 Transitional
47 ...and these character encodings:
50 * Any encoding iconv supports (with crippled internationalization support)
52 These defaults reflect what my choices would be if I were authoring an
53 HTML document, however, what you choose depends on the nature of your
54 codebase. If you don't know what doctype you are using, you can determine
55 the doctype from this identifier at the top of your source code:
57 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
58 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
60 ...and the character encoding from this code:
62 <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
64 If the character encoding declaration is missing, STOP NOW, and
65 read 'docs/enduser-utf8.html' (web accessible at
66 http://htmlpurifier.org/docs/enduser-utf8.html). In fact, even if it is
67 present, read this document anyway, as many websites specify their
68 document's character encoding incorrectly.
71 ---------------------------------------------------------------------------
72 3. Including the library
74 The procedure is quite simple:
76 require_once '/path/to/library/HTMLPurifier.auto.php';
78 This will setup an autoloader, so the library's files are only included
81 Only the contents in the library/ folder are necessary, so you can remove
82 everything else when using HTML Purifier in a production environment.
84 Advanced users, read on; other users can skip to section 4.
86 Autoload compatibility
87 ----------------------
89 HTML Purifier attempts to be as smart as possible when registering an
90 autoloader, but there are some cases where you will need to change
91 your own code to accomodate HTML Purifier. These are those cases:
93 PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
94 Because spl_autoload_register() doesn't exist in early versions
95 of PHP 5, HTML Purifier has no way of adding itself to the autoload
96 stack. Modify your __autoload function to test
97 HTMLPurifier_Bootstrap::autoload($class)
99 For example, suppose your autoload function looks like this:
101 function __autoload($class) {
102 require str_replace('_', '/', $class) . '.php';
106 A modified version with HTML Purifier would look like this:
108 function __autoload($class) {
109 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
110 require str_replace('_', '/', $class) . '.php';
114 Note that there *is* some custom behavior in our autoloader; the
115 original autoloader in our example would work for 99% of the time,
116 but would fail when including language files.
118 AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
119 spl_autoload_register() has the curious behavior of disabling
120 the existing __autoload() handler. Users need to explicitly
121 spl_autoload_register('__autoload'). Because we use SPL when it
122 is available, __autoload() will ALWAYS be disabled. If __autoload()
123 is declared before HTML Purifier is loaded, this is not a problem:
124 HTML Purifier will register the function for you. But if it is
125 declared afterwards, it will mysteriously not work. This
126 snippet of code (after your autoloader is defined) will fix it:
128 spl_autoload_register('__autoload')
130 Users should also be on guard if they use a version of PHP previous
131 to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
132 for you, which can collide with an autoloader that was added by *you*
136 For better performance
137 ----------------------
139 Opcode caches, which greatly speed up PHP initialization for scripts
140 with large amounts of code (HTML Purifier included), don't like
141 autoloaders. We offer an include file that includes all of HTML Purifier's
142 files in one go in an opcode cache friendly manner:
144 // If /path/to/library isn't already in your include path, uncomment
146 // require '/path/to/library/HTMLPurifier.path.php';
148 require 'HTMLPurifier.includes.php';
150 Optional components still need to be included--you'll know if you try to
151 use a feature and you get a class doesn't exists error! The autoloader
152 can be used in conjunction with this approach to catch classes that are
153 missing. Simply add this afterwards:
155 require 'HTMLPurifier.autoload.php';
160 HTML Purifier has a standalone distribution; you can also generate
161 a standalone file from the full version by running the script
162 maintenance/generate-standalone.php . The standalone version has the
163 benefit of having most of its code in one file, so parsing is much
164 faster and the library is easier to manage.
166 If HTMLPurifier.standalone.php exists in the library directory, you
167 can use it like this:
169 require '/path/to/HTMLPurifier.standalone.php';
171 This is equivalent to including HTMLPurifier.includes.php, except that
172 the contents of standalone/ will be added to your path. To override this
173 behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
174 be found (usually, this will be one directory up, the "true" library
175 directory in full distributions). Don't forget to set your path too!
177 The autoloader can be added to the end to ensure the classes are
178 loaded when necessary; otherwise you can manually include them.
179 To use the autoloader, use this:
181 require 'HTMLPurifier.autoload.php';
186 HTMLPurifier.auto.php performs a number of operations that can be done
187 individually. These are:
189 HTMLPurifier.path.php
190 Puts /path/to/library in the include path. For high performance,
191 this should be done in php.ini.
193 HTMLPurifier.autoload.php
194 Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
196 You can do these operations by yourself--in fact, you must modify your own
197 autoload handler if you are using a version of PHP earlier than PHP 5.1.2
198 (See "Autoload compatibility" above).
201 ---------------------------------------------------------------------------
204 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
205 Purifier needs to be told what to do. If you answer no to any of these
206 questions, read on; otherwise, you can skip to the next section (or, if you're
207 into configuring things just for the heck of it, skip to 4.3).
210 * Am I using XHTML 1.0 Transitional?
212 If you answered no to any of these questions, instantiate a configuration
215 $config = HTMLPurifier_Config::createDefault();
218 4.1. Setting a different character encoding
220 You really shouldn't use any other encoding except UTF-8, especially if you
221 plan to support multilingual websites (read section three for more details).
222 However, switching to UTF-8 is not always immediately feasible, so we can
225 HTML Purifier uses iconv to support other character encodings, as such,
226 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
227 HTML Purifier supports with this code:
229 $config->set('Core', 'Encoding', /* put your encoding here */);
231 An example usage for Latin-1 websites (the most common encoding for English
234 $config->set('Core', 'Encoding', 'ISO-8859-1');
236 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
237 fact that any character not supported by that encoding will be silently
238 dropped, EVEN if it is ampersand escaped. If you want to work around
239 this, you are welcome to read docs/enduser-utf8.html for a fix,
240 but please be cognizant of the issues the "solution" creates (for this
241 reason, I do not include the solution in this document).
244 4.2. Setting a different doctype
246 For those of you using HTML 4.01 Transitional, you can disable
247 XHTML output like this:
249 $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
251 Other supported doctypes include:
254 * HTML 4.01 Transitional
256 * XHTML 1.0 Transitional
262 There are more configuration directives which can be read about
263 here: <http://htmlpurifier.org/live/configdoc/plain.html> They're a bit boring,
264 but they can help out for those of you who like to exert maximum control over
265 your code. Some of the more interesting ones are configurable at the
266 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
269 For example, you can fine tune allowed elements and attributes, convert
270 relative URLs to absolute ones, and even autoparagraph input text! These
271 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
272 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
275 $config->set('Namespace', 'Directive', $value);
279 $config->set('HTML', 'Allowed', 'p,b,a[href],i');
280 $config->set('URI', 'Base', 'http://www.example.com');
281 $config->set('URI', 'MakeAbsolute', true);
282 $config->set('AutoFormat', 'AutoParagraph', true);
285 ---------------------------------------------------------------------------
288 HTML Purifier generates some cache files (generally one or two) to speed up
289 its execution. For maximum performance, make sure that
290 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
292 If you are in the library/ folder of HTML Purifier, you can set the
293 appropriate permissions using:
295 chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
297 If the above command doesn't work, you may need to assign write permissions
298 to all. This may be necessary if your webserver runs as nobody, but is
299 not recommended since it means any other user can write files in the
302 chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
304 You can also chmod files via your FTP client; this option
305 is usually accessible by right clicking the corresponding directory and
306 then selecting "chmod" or "file permissions".
308 Starting with 2.0.1, HTML Purifier will generate friendly error messages
309 that will tell you exactly what you have to chmod the directory to, if in doubt,
312 If you are unable or unwilling to give write permissions to the cache
313 directory, you can either disable the cache (and suffer a performance
316 $config->set('Core', 'DefinitionCache', null);
318 Or move the cache directory somewhere else (no trailing slash):
320 $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
323 ---------------------------------------------------------------------------
326 The interface is mind-numbingly simple:
328 $purifier = new HTMLPurifier();
329 $clean_html = $purifier->purify( $dirty_html );
331 ...or, if you're using the configuration object:
333 $purifier = new HTMLPurifier($config);
334 $clean_html = $purifier->purify( $dirty_html );
336 That's it! For more examples, check out docs/examples/ (they aren't very
337 different though). Also, docs/enduser-slow.html gives advice on what to
338 do if HTML Purifier is slowing down your application.
341 ---------------------------------------------------------------------------
344 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
345 writable by the webserver (see Section 5: Caching above for details).
346 If your website is in UTF-8 and XHTML Transitional, use this code:
349 require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
351 $purifier = new HTMLPurifier();
352 $clean_html = $purifier->purify($dirty_html);
355 If your website is in a different encoding or doctype, use this code:
358 require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
360 $config = HTMLPurifier_Config::createDefault();
361 $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
362 $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
363 $purifier = new HTMLPurifier($config);
365 $clean_html = $purifier->purify($dirty_html);