Update configuration scanner to parse new format.
[htmlpurifier.git] / INSTALL
blob2b4069e243d2d7ef0257d16832d580cbc7e162c7
2 Install
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
12 with these contents.
15 ---------------------------------------------------------------------------
16 1.  Compatibility
18 HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.5 and
19 up. It has no core dependencies with other libraries. PHP
20 4 support was deprecated on December 31, 2007 with HTML Purifier 3.0.0.
22 These optional extensions can enhance the capabilities of HTML Purifier:
24     * iconv  : Converts text to and from non-UTF-8 encodings
25     * bcmath : Used for unit conversion and imagecrash protection
26     * tidy   : Used for pretty-printing HTML
29 ---------------------------------------------------------------------------
30 2.  Reconnaissance
32 A big plus of HTML Purifier is its inerrant support of standards, so
33 your web-pages should be standards-compliant.  (They should also use
34 semantic markup, but that's another issue altogether, one HTML Purifier
35 cannot fix without reading your mind.)
37 HTML Purifier can process these doctypes:
39 * XHTML 1.0 Transitional (default)
40 * XHTML 1.0 Strict
41 * HTML 4.01 Transitional
42 * HTML 4.01 Strict
43 * XHTML 1.1
45 ...and these character encodings:
47 * UTF-8 (default)
48 * Any encoding iconv supports (with crippled internationalization support)
50 These defaults reflect what my choices would be if I were authoring an
51 HTML document, however, what you choose depends on the nature of your
52 codebase.  If you don't know what doctype you are using, you can determine
53 the doctype from this identifier at the top of your source code:
55     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
56         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
58 ...and the character encoding from this code:
60     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
62 If the character encoding declaration is missing, STOP NOW, and
63 read 'docs/enduser-utf8.html' (web accessible at
64 http://htmlpurifier.org/docs/enduser-utf8.html).  In fact, even if it is
65 present, read this document anyway, as many websites specify their
66 document's character encoding incorrectly.
69 ---------------------------------------------------------------------------
70 3.  Including the library
72 The procedure is quite simple:
74     require_once '/path/to/library/HTMLPurifier.auto.php';
76 This will setup an autoloader, so the library's files are only included
77 when you use them.
79 Only the contents in the library/ folder are necessary, so you can remove
80 everything else when using HTML Purifier in a production environment.
82 If you installed HTML Purifier via PEAR, all you need to do is:
84     require_once 'HTMLPurifier.auto.php';
86 Please note that the usual PEAR practice of including just the classes you
87 want will not work with HTML Purifier's autoloading scheme.
89 Advanced users, read on; other users can skip to section 4.
91 Autoload compatibility
92 ----------------------
94     HTML Purifier attempts to be as smart as possible when registering an
95     autoloader, but there are some cases where you will need to change
96     your own code to accomodate HTML Purifier. These are those cases:
98     PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
99         Because spl_autoload_register() doesn't exist in early versions
100         of PHP 5, HTML Purifier has no way of adding itself to the autoload
101         stack. Modify your __autoload function to test
102         HTMLPurifier_Bootstrap::autoload($class)
104         For example, suppose your autoload function looks like this:
106             function __autoload($class) {
107                 require str_replace('_', '/', $class) . '.php';
108                 return true;
109             }
111         A modified version with HTML Purifier would look like this:
113             function __autoload($class) {
114                 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
115                 require str_replace('_', '/', $class) . '.php';
116                 return true;
117             }
119         Note that there *is* some custom behavior in our autoloader; the
120         original autoloader in our example would work for 99% of the time,
121         but would fail when including language files.
123     AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
124         spl_autoload_register() has the curious behavior of disabling
125         the existing __autoload() handler. Users need to explicitly
126         spl_autoload_register('__autoload'). Because we use SPL when it
127         is available, __autoload() will ALWAYS be disabled. If __autoload()
128         is declared before HTML Purifier is loaded, this is not a problem:
129         HTML Purifier will register the function for you. But if it is
130         declared afterwards, it will mysteriously not work. This
131         snippet of code (after your autoloader is defined) will fix it:
133             spl_autoload_register('__autoload')
135     Users should also be on guard if they use a version of PHP previous
136     to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
137     for you, which can collide with an autoloader that was added by *you*
138     later.
141 For better performance
142 ----------------------
144     Opcode caches, which greatly speed up PHP initialization for scripts
145     with large amounts of code (HTML Purifier included), don't like
146     autoloaders. We offer an include file that includes all of HTML Purifier's
147     files in one go in an opcode cache friendly manner:
149         // If /path/to/library isn't already in your include path, uncomment
150         // the below line:
151         // require '/path/to/library/HTMLPurifier.path.php';
153         require 'HTMLPurifier.includes.php';
155     Optional components still need to be included--you'll know if you try to
156     use a feature and you get a class doesn't exists error! The autoloader
157     can be used in conjunction with this approach to catch classes that are
158     missing. Simply add this afterwards:
160         require 'HTMLPurifier.autoload.php';
162 Standalone version
163 ------------------
165     HTML Purifier has a standalone distribution; you can also generate
166     a standalone file from the full version by running the script
167     maintenance/generate-standalone.php . The standalone version has the
168     benefit of having most of its code in one file, so parsing is much
169     faster and the library is easier to manage.
171     If HTMLPurifier.standalone.php exists in the library directory, you
172     can use it like this:
174         require '/path/to/HTMLPurifier.standalone.php';
176     This is equivalent to including HTMLPurifier.includes.php, except that
177     the contents of standalone/ will be added to your path. To override this
178     behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
179     be found (usually, this will be one directory up, the "true" library
180     directory in full distributions). Don't forget to set your path too!
182     The autoloader can be added to the end to ensure the classes are
183     loaded when necessary; otherwise you can manually include them.
184     To use the autoloader, use this:
186         require 'HTMLPurifier.autoload.php';
188 For advanced users
189 ------------------
191     HTMLPurifier.auto.php performs a number of operations that can be done
192     individually. These are:
194         HTMLPurifier.path.php
195             Puts /path/to/library in the include path. For high performance,
196             this should be done in php.ini.
198         HTMLPurifier.autoload.php
199             Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
201     You can do these operations by yourself--in fact, you must modify your own
202     autoload handler if you are using a version of PHP earlier than PHP 5.1.2
203     (See "Autoload compatibility" above).
206 ---------------------------------------------------------------------------
207 4. Configuration
209 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
210 Purifier needs to be told what to do.  If you answer no to any of these
211 questions, read on; otherwise, you can skip to the next section (or, if you're
212 into configuring things just for the heck of it, skip to 4.3).
214 * Am I using UTF-8?
215 * Am I using XHTML 1.0 Transitional?
217 If you answered no to any of these questions, instantiate a configuration
218 object and read on:
220     $config = HTMLPurifier_Config::createDefault();
223 4.1. Setting a different character encoding
225 You really shouldn't use any other encoding except UTF-8, especially if you
226 plan to support multilingual websites (read section three for more details).
227 However, switching to UTF-8 is not always immediately feasible, so we can
228 adapt.
230 HTML Purifier uses iconv to support other character encodings, as such,
231 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
232 HTML Purifier supports with this code:
234     $config->set('Core.Encoding', /* put your encoding here */);
236 An example usage for Latin-1 websites (the most common encoding for English
237 websites):
239     $config->set('Core.Encoding', 'ISO-8859-1');
241 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
242 fact that any character not supported by that encoding will be silently
243 dropped, EVEN if it is ampersand escaped.  If you want to work around
244 this, you are welcome to read docs/enduser-utf8.html for a fix,
245 but please be cognizant of the issues the "solution" creates (for this
246 reason, I do not include the solution in this document).
249 4.2. Setting a different doctype
251 For those of you using HTML 4.01 Transitional, you can disable
252 XHTML output like this:
254     $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
256 Other supported doctypes include:
258     * HTML 4.01 Strict
259     * HTML 4.01 Transitional
260     * XHTML 1.0 Strict
261     * XHTML 1.0 Transitional
262     * XHTML 1.1
265 4.3. Other settings
267 There are more configuration directives which can be read about
268 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
269 but they can help out for those of you who like to exert maximum control over
270 your code.  Some of the more interesting ones are configurable at the
271 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
272 for your own system.
274 For example, you can fine tune allowed elements and attributes, convert
275 relative URLs to absolute ones, and even autoparagraph input text! These
276 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
277 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
278 translates to:
280     $config->set('Namespace.Directive', $value);
282 E.g.
284     $config->set('HTML.Allowed', 'p,b,a[href],i');
285     $config->set('URI.Base', 'http://www.example.com');
286     $config->set('URI.MakeAbsolute', true);
287     $config->set('AutoFormat.AutoParagraph', true);
290 ---------------------------------------------------------------------------
291 5. Caching
293 HTML Purifier generates some cache files (generally one or two) to speed up
294 its execution. For maximum performance, make sure that
295 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
297 If you are in the library/ folder of HTML Purifier, you can set the
298 appropriate permissions using:
300     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
302 If the above command doesn't work, you may need to assign write permissions
303 to all. This may be necessary if your webserver runs as nobody, but is
304 not recommended since it means any other user can write files in the
305 directory. Use:
307     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
309 You can also chmod files via your FTP client; this option
310 is usually accessible by right clicking the corresponding directory and
311 then selecting "chmod" or "file permissions".
313 Starting with 2.0.1, HTML Purifier will generate friendly error messages
314 that will tell you exactly what you have to chmod the directory to, if in doubt,
315 follow its advice.
317 If you are unable or unwilling to give write permissions to the cache
318 directory, you can either disable the cache (and suffer a performance
319 hit):
321     $config->set('Core.DefinitionCache', null);
323 Or move the cache directory somewhere else (no trailing slash):
325     $config->set('Cache.SerializerPath', '/home/user/absolute/path');
328 ---------------------------------------------------------------------------
329 6.   Using the code
331 The interface is mind-numbingly simple:
333     $purifier = new HTMLPurifier();
334     $clean_html = $purifier->purify( $dirty_html );
336 ...or, if you're using the configuration object:
338     $purifier = new HTMLPurifier($config);
339     $clean_html = $purifier->purify( $dirty_html );
341 That's it!  For more examples, check out docs/examples/ (they aren't very
342 different though).  Also, docs/enduser-slow.html gives advice on what to
343 do if HTML Purifier is slowing down your application.
346 ---------------------------------------------------------------------------
347 7.   Quick install
349 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
350 writable by the webserver (see Section 5: Caching above for details).
351 If your website is in UTF-8 and XHTML Transitional, use this code:
353 <?php
354     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
356     $purifier = new HTMLPurifier();
357     $clean_html = $purifier->purify($dirty_html);
360 If your website is in a different encoding or doctype, use this code:
362 <?php
363     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
365     $config = HTMLPurifier_Config::createDefault();
366     $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding
367     $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
368     $purifier = new HTMLPurifier($config);
370     $clean_html = $purifier->purify($dirty_html);
373     vim: et sw=4 sts=4