Release 4.8.0
[htmlpurifier.git] / INSTALL
blobe6dd02afa7861796a1ec119e549bd7048508c957
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 and PHP 7, and is actively tested from PHP 5.0.5
19 and up. It has no core dependencies with other libraries.
21 These optional extensions can enhance the capabilities of HTML Purifier:
23     * iconv  : Converts text to and from non-UTF-8 encodings
24     * bcmath : Used for unit conversion and imagecrash protection
25     * tidy   : Used for pretty-printing HTML
27 These optional libraries can enhance the capabilities of HTML Purifier:
29     * CSSTidy : Clean CSS stylesheets using %Core.ExtractStyleBlocks
30         Note: You should use the modernized fork of CSSTidy available
31         at https://github.com/Cerdic/CSSTidy
32     * Net_IDNA2 (PEAR) : IRI support using %Core.EnableIDNA
33         Note: This is not necessary for PHP 5.3 or later
35 ---------------------------------------------------------------------------
36 2.  Reconnaissance
38 A big plus of HTML Purifier is its inerrant support of standards, so
39 your web-pages should be standards-compliant.  (They should also use
40 semantic markup, but that's another issue altogether, one HTML Purifier
41 cannot fix without reading your mind.)
43 HTML Purifier can process these doctypes:
45 * XHTML 1.0 Transitional (default)
46 * XHTML 1.0 Strict
47 * HTML 4.01 Transitional
48 * HTML 4.01 Strict
49 * XHTML 1.1
51 ...and these character encodings:
53 * UTF-8 (default)
54 * Any encoding iconv supports (with crippled internationalization support)
56 These defaults reflect what my choices would be if I were authoring an
57 HTML document, however, what you choose depends on the nature of your
58 codebase.  If you don't know what doctype you are using, you can determine
59 the doctype from this identifier at the top of your source code:
61     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
62         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
64 ...and the character encoding from this code:
66     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
68 If the character encoding declaration is missing, STOP NOW, and
69 read 'docs/enduser-utf8.html' (web accessible at
70 http://htmlpurifier.org/docs/enduser-utf8.html).  In fact, even if it is
71 present, read this document anyway, as many websites specify their
72 document's character encoding incorrectly.
75 ---------------------------------------------------------------------------
76 3.  Including the library
78 The procedure is quite simple:
80     require_once '/path/to/library/HTMLPurifier.auto.php';
82 This will setup an autoloader, so the library's files are only included
83 when you use them.
85 Only the contents in the library/ folder are necessary, so you can remove
86 everything else when using HTML Purifier in a production environment.
88 If you installed HTML Purifier via PEAR, all you need to do is:
90     require_once 'HTMLPurifier.auto.php';
92 Please note that the usual PEAR practice of including just the classes you
93 want will not work with HTML Purifier's autoloading scheme.
95 Advanced users, read on; other users can skip to section 4.
97 Autoload compatibility
98 ----------------------
100     HTML Purifier attempts to be as smart as possible when registering an
101     autoloader, but there are some cases where you will need to change
102     your own code to accomodate HTML Purifier. These are those cases:
104     PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
105         Because spl_autoload_register() doesn't exist in early versions
106         of PHP 5, HTML Purifier has no way of adding itself to the autoload
107         stack. Modify your __autoload function to test
108         HTMLPurifier_Bootstrap::autoload($class)
110         For example, suppose your autoload function looks like this:
112             function __autoload($class) {
113                 require str_replace('_', '/', $class) . '.php';
114                 return true;
115             }
117         A modified version with HTML Purifier would look like this:
119             function __autoload($class) {
120                 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
121                 require str_replace('_', '/', $class) . '.php';
122                 return true;
123             }
125         Note that there *is* some custom behavior in our autoloader; the
126         original autoloader in our example would work for 99% of the time,
127         but would fail when including language files.
129     AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
130         spl_autoload_register() has the curious behavior of disabling
131         the existing __autoload() handler. Users need to explicitly
132         spl_autoload_register('__autoload'). Because we use SPL when it
133         is available, __autoload() will ALWAYS be disabled. If __autoload()
134         is declared before HTML Purifier is loaded, this is not a problem:
135         HTML Purifier will register the function for you. But if it is
136         declared afterwards, it will mysteriously not work. This
137         snippet of code (after your autoloader is defined) will fix it:
139             spl_autoload_register('__autoload')
141     Users should also be on guard if they use a version of PHP previous
142     to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
143     for you, which can collide with an autoloader that was added by *you*
144     later.
147 For better performance
148 ----------------------
150     Opcode caches, which greatly speed up PHP initialization for scripts
151     with large amounts of code (HTML Purifier included), don't like
152     autoloaders. We offer an include file that includes all of HTML Purifier's
153     files in one go in an opcode cache friendly manner:
155         // If /path/to/library isn't already in your include path, uncomment
156         // the below line:
157         // require '/path/to/library/HTMLPurifier.path.php';
159         require 'HTMLPurifier.includes.php';
161     Optional components still need to be included--you'll know if you try to
162     use a feature and you get a class doesn't exists error! The autoloader
163     can be used in conjunction with this approach to catch classes that are
164     missing. Simply add this afterwards:
166         require 'HTMLPurifier.autoload.php';
168 Standalone version
169 ------------------
171     HTML Purifier has a standalone distribution; you can also generate
172     a standalone file from the full version by running the script
173     maintenance/generate-standalone.php . The standalone version has the
174     benefit of having most of its code in one file, so parsing is much
175     faster and the library is easier to manage.
177     If HTMLPurifier.standalone.php exists in the library directory, you
178     can use it like this:
180         require '/path/to/HTMLPurifier.standalone.php';
182     This is equivalent to including HTMLPurifier.includes.php, except that
183     the contents of standalone/ will be added to your path. To override this
184     behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
185     be found (usually, this will be one directory up, the "true" library
186     directory in full distributions). Don't forget to set your path too!
188     The autoloader can be added to the end to ensure the classes are
189     loaded when necessary; otherwise you can manually include them.
190     To use the autoloader, use this:
192         require 'HTMLPurifier.autoload.php';
194 For advanced users
195 ------------------
197     HTMLPurifier.auto.php performs a number of operations that can be done
198     individually. These are:
200         HTMLPurifier.path.php
201             Puts /path/to/library in the include path. For high performance,
202             this should be done in php.ini.
204         HTMLPurifier.autoload.php
205             Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
207     You can do these operations by yourself--in fact, you must modify your own
208     autoload handler if you are using a version of PHP earlier than PHP 5.1.2
209     (See "Autoload compatibility" above).
212 ---------------------------------------------------------------------------
213 4. Configuration
215 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
216 Purifier needs to be told what to do.  If you answer no to any of these
217 questions, read on; otherwise, you can skip to the next section (or, if you're
218 into configuring things just for the heck of it, skip to 4.3).
220 * Am I using UTF-8?
221 * Am I using XHTML 1.0 Transitional?
223 If you answered no to any of these questions, instantiate a configuration
224 object and read on:
226     $config = HTMLPurifier_Config::createDefault();
229 4.1. Setting a different character encoding
231 You really shouldn't use any other encoding except UTF-8, especially if you
232 plan to support multilingual websites (read section three for more details).
233 However, switching to UTF-8 is not always immediately feasible, so we can
234 adapt.
236 HTML Purifier uses iconv to support other character encodings, as such,
237 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
238 HTML Purifier supports with this code:
240     $config->set('Core.Encoding', /* put your encoding here */);
242 An example usage for Latin-1 websites (the most common encoding for English
243 websites):
245     $config->set('Core.Encoding', 'ISO-8859-1');
247 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
248 fact that any character not supported by that encoding will be silently
249 dropped, EVEN if it is ampersand escaped.  If you want to work around
250 this, you are welcome to read docs/enduser-utf8.html for a fix,
251 but please be cognizant of the issues the "solution" creates (for this
252 reason, I do not include the solution in this document).
255 4.2. Setting a different doctype
257 For those of you using HTML 4.01 Transitional, you can disable
258 XHTML output like this:
260     $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
262 Other supported doctypes include:
264     * HTML 4.01 Strict
265     * HTML 4.01 Transitional
266     * XHTML 1.0 Strict
267     * XHTML 1.0 Transitional
268     * XHTML 1.1
271 4.3. Other settings
273 There are more configuration directives which can be read about
274 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
275 but they can help out for those of you who like to exert maximum control over
276 your code.  Some of the more interesting ones are configurable at the
277 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
278 for your own system.
280 For example, you can fine tune allowed elements and attributes, convert
281 relative URLs to absolute ones, and even autoparagraph input text! These
282 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
283 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
284 translates to:
286     $config->set('Namespace.Directive', $value);
288 E.g.
290     $config->set('HTML.Allowed', 'p,b,a[href],i');
291     $config->set('URI.Base', 'http://www.example.com');
292     $config->set('URI.MakeAbsolute', true);
293     $config->set('AutoFormat.AutoParagraph', true);
296 ---------------------------------------------------------------------------
297 5. Caching
299 HTML Purifier generates some cache files (generally one or two) to speed up
300 its execution. For maximum performance, make sure that
301 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
303 If you are in the library/ folder of HTML Purifier, you can set the
304 appropriate permissions using:
306     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
308 If the above command doesn't work, you may need to assign write permissions
309 to group:
311     chmod -R 0775 HTMLPurifier/DefinitionCache/Serializer
313 You can also chmod files via your FTP client; this option
314 is usually accessible by right clicking the corresponding directory and
315 then selecting "chmod" or "file permissions".
317 Starting with 2.0.1, HTML Purifier will generate friendly error messages
318 that will tell you exactly what you have to chmod the directory to, if in doubt,
319 follow its advice.
321 If you are unable or unwilling to give write permissions to the cache
322 directory, you can either disable the cache (and suffer a performance
323 hit):
325     $config->set('Core.DefinitionCache', null);
327 Or move the cache directory somewhere else (no trailing slash):
329     $config->set('Cache.SerializerPath', '/home/user/absolute/path');
332 ---------------------------------------------------------------------------
333 6.   Using the code
335 The interface is mind-numbingly simple:
337     $purifier = new HTMLPurifier($config);
338     $clean_html = $purifier->purify( $dirty_html );
340 That's it!  For more examples, check out docs/examples/ (they aren't very
341 different though).  Also, docs/enduser-slow.html gives advice on what to
342 do if HTML Purifier is slowing down your application.
345 ---------------------------------------------------------------------------
346 7.   Quick install
348 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
349 writable by the webserver (see Section 5: Caching above for details).
350 If your website is in UTF-8 and XHTML Transitional, use this code:
352 <?php
353     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
355     $config = HTMLPurifier_Config::createDefault();
356     $purifier = new HTMLPurifier($config);
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