Release 4.7.0.
[htmlpurifier.git] / INSTALL
blob677c04aa049597985c4c02b7787f8ce3e2ac0a89
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.
21 HTML Purifier is not compatible with zend.ze1_compatibility_mode.
23 These optional extensions can enhance the capabilities of HTML Purifier:
25     * iconv  : Converts text to and from non-UTF-8 encodings
26     * bcmath : Used for unit conversion and imagecrash protection
27     * tidy   : Used for pretty-printing HTML
29 These optional libraries can enhance the capabilities of HTML Purifier:
31     * CSSTidy : Clean CSS stylesheets using %Core.ExtractStyleBlocks
32     * Net_IDNA2 (PEAR) : IRI support using %Core.EnableIDNA
34 ---------------------------------------------------------------------------
35 2.  Reconnaissance
37 A big plus of HTML Purifier is its inerrant support of standards, so
38 your web-pages should be standards-compliant.  (They should also use
39 semantic markup, but that's another issue altogether, one HTML Purifier
40 cannot fix without reading your mind.)
42 HTML Purifier can process these doctypes:
44 * XHTML 1.0 Transitional (default)
45 * XHTML 1.0 Strict
46 * HTML 4.01 Transitional
47 * HTML 4.01 Strict
48 * XHTML 1.1
50 ...and these character encodings:
52 * UTF-8 (default)
53 * Any encoding iconv supports (with crippled internationalization support)
55 These defaults reflect what my choices would be if I were authoring an
56 HTML document, however, what you choose depends on the nature of your
57 codebase.  If you don't know what doctype you are using, you can determine
58 the doctype from this identifier at the top of your source code:
60     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
61         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
63 ...and the character encoding from this code:
65     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
67 If the character encoding declaration is missing, STOP NOW, and
68 read 'docs/enduser-utf8.html' (web accessible at
69 http://htmlpurifier.org/docs/enduser-utf8.html).  In fact, even if it is
70 present, read this document anyway, as many websites specify their
71 document's character encoding incorrectly.
74 ---------------------------------------------------------------------------
75 3.  Including the library
77 The procedure is quite simple:
79     require_once '/path/to/library/HTMLPurifier.auto.php';
81 This will setup an autoloader, so the library's files are only included
82 when you use them.
84 Only the contents in the library/ folder are necessary, so you can remove
85 everything else when using HTML Purifier in a production environment.
87 If you installed HTML Purifier via PEAR, all you need to do is:
89     require_once 'HTMLPurifier.auto.php';
91 Please note that the usual PEAR practice of including just the classes you
92 want will not work with HTML Purifier's autoloading scheme.
94 Advanced users, read on; other users can skip to section 4.
96 Autoload compatibility
97 ----------------------
99     HTML Purifier attempts to be as smart as possible when registering an
100     autoloader, but there are some cases where you will need to change
101     your own code to accomodate HTML Purifier. These are those cases:
103     PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
104         Because spl_autoload_register() doesn't exist in early versions
105         of PHP 5, HTML Purifier has no way of adding itself to the autoload
106         stack. Modify your __autoload function to test
107         HTMLPurifier_Bootstrap::autoload($class)
109         For example, suppose your autoload function looks like this:
111             function __autoload($class) {
112                 require str_replace('_', '/', $class) . '.php';
113                 return true;
114             }
116         A modified version with HTML Purifier would look like this:
118             function __autoload($class) {
119                 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
120                 require str_replace('_', '/', $class) . '.php';
121                 return true;
122             }
124         Note that there *is* some custom behavior in our autoloader; the
125         original autoloader in our example would work for 99% of the time,
126         but would fail when including language files.
128     AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
129         spl_autoload_register() has the curious behavior of disabling
130         the existing __autoload() handler. Users need to explicitly
131         spl_autoload_register('__autoload'). Because we use SPL when it
132         is available, __autoload() will ALWAYS be disabled. If __autoload()
133         is declared before HTML Purifier is loaded, this is not a problem:
134         HTML Purifier will register the function for you. But if it is
135         declared afterwards, it will mysteriously not work. This
136         snippet of code (after your autoloader is defined) will fix it:
138             spl_autoload_register('__autoload')
140     Users should also be on guard if they use a version of PHP previous
141     to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
142     for you, which can collide with an autoloader that was added by *you*
143     later.
146 For better performance
147 ----------------------
149     Opcode caches, which greatly speed up PHP initialization for scripts
150     with large amounts of code (HTML Purifier included), don't like
151     autoloaders. We offer an include file that includes all of HTML Purifier's
152     files in one go in an opcode cache friendly manner:
154         // If /path/to/library isn't already in your include path, uncomment
155         // the below line:
156         // require '/path/to/library/HTMLPurifier.path.php';
158         require 'HTMLPurifier.includes.php';
160     Optional components still need to be included--you'll know if you try to
161     use a feature and you get a class doesn't exists error! The autoloader
162     can be used in conjunction with this approach to catch classes that are
163     missing. Simply add this afterwards:
165         require 'HTMLPurifier.autoload.php';
167 Standalone version
168 ------------------
170     HTML Purifier has a standalone distribution; you can also generate
171     a standalone file from the full version by running the script
172     maintenance/generate-standalone.php . The standalone version has the
173     benefit of having most of its code in one file, so parsing is much
174     faster and the library is easier to manage.
176     If HTMLPurifier.standalone.php exists in the library directory, you
177     can use it like this:
179         require '/path/to/HTMLPurifier.standalone.php';
181     This is equivalent to including HTMLPurifier.includes.php, except that
182     the contents of standalone/ will be added to your path. To override this
183     behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
184     be found (usually, this will be one directory up, the "true" library
185     directory in full distributions). Don't forget to set your path too!
187     The autoloader can be added to the end to ensure the classes are
188     loaded when necessary; otherwise you can manually include them.
189     To use the autoloader, use this:
191         require 'HTMLPurifier.autoload.php';
193 For advanced users
194 ------------------
196     HTMLPurifier.auto.php performs a number of operations that can be done
197     individually. These are:
199         HTMLPurifier.path.php
200             Puts /path/to/library in the include path. For high performance,
201             this should be done in php.ini.
203         HTMLPurifier.autoload.php
204             Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
206     You can do these operations by yourself--in fact, you must modify your own
207     autoload handler if you are using a version of PHP earlier than PHP 5.1.2
208     (See "Autoload compatibility" above).
211 ---------------------------------------------------------------------------
212 4. Configuration
214 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
215 Purifier needs to be told what to do.  If you answer no to any of these
216 questions, read on; otherwise, you can skip to the next section (or, if you're
217 into configuring things just for the heck of it, skip to 4.3).
219 * Am I using UTF-8?
220 * Am I using XHTML 1.0 Transitional?
222 If you answered no to any of these questions, instantiate a configuration
223 object and read on:
225     $config = HTMLPurifier_Config::createDefault();
228 4.1. Setting a different character encoding
230 You really shouldn't use any other encoding except UTF-8, especially if you
231 plan to support multilingual websites (read section three for more details).
232 However, switching to UTF-8 is not always immediately feasible, so we can
233 adapt.
235 HTML Purifier uses iconv to support other character encodings, as such,
236 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
237 HTML Purifier supports with this code:
239     $config->set('Core.Encoding', /* put your encoding here */);
241 An example usage for Latin-1 websites (the most common encoding for English
242 websites):
244     $config->set('Core.Encoding', 'ISO-8859-1');
246 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
247 fact that any character not supported by that encoding will be silently
248 dropped, EVEN if it is ampersand escaped.  If you want to work around
249 this, you are welcome to read docs/enduser-utf8.html for a fix,
250 but please be cognizant of the issues the "solution" creates (for this
251 reason, I do not include the solution in this document).
254 4.2. Setting a different doctype
256 For those of you using HTML 4.01 Transitional, you can disable
257 XHTML output like this:
259     $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
261 Other supported doctypes include:
263     * HTML 4.01 Strict
264     * HTML 4.01 Transitional
265     * XHTML 1.0 Strict
266     * XHTML 1.0 Transitional
267     * XHTML 1.1
270 4.3. Other settings
272 There are more configuration directives which can be read about
273 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
274 but they can help out for those of you who like to exert maximum control over
275 your code.  Some of the more interesting ones are configurable at the
276 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
277 for your own system.
279 For example, you can fine tune allowed elements and attributes, convert
280 relative URLs to absolute ones, and even autoparagraph input text! These
281 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
282 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
283 translates to:
285     $config->set('Namespace.Directive', $value);
287 E.g.
289     $config->set('HTML.Allowed', 'p,b,a[href],i');
290     $config->set('URI.Base', 'http://www.example.com');
291     $config->set('URI.MakeAbsolute', true);
292     $config->set('AutoFormat.AutoParagraph', true);
295 ---------------------------------------------------------------------------
296 5. Caching
298 HTML Purifier generates some cache files (generally one or two) to speed up
299 its execution. For maximum performance, make sure that
300 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
302 If you are in the library/ folder of HTML Purifier, you can set the
303 appropriate permissions using:
305     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
307 If the above command doesn't work, you may need to assign write permissions
308 to all. This may be necessary if your webserver runs as nobody, but is
309 not recommended since it means any other user can write files in the
310 directory. Use:
312     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
314 You can also chmod files via your FTP client; this option
315 is usually accessible by right clicking the corresponding directory and
316 then selecting "chmod" or "file permissions".
318 Starting with 2.0.1, HTML Purifier will generate friendly error messages
319 that will tell you exactly what you have to chmod the directory to, if in doubt,
320 follow its advice.
322 If you are unable or unwilling to give write permissions to the cache
323 directory, you can either disable the cache (and suffer a performance
324 hit):
326     $config->set('Core.DefinitionCache', null);
328 Or move the cache directory somewhere else (no trailing slash):
330     $config->set('Cache.SerializerPath', '/home/user/absolute/path');
333 ---------------------------------------------------------------------------
334 6.   Using the code
336 The interface is mind-numbingly simple:
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     $config = HTMLPurifier_Config::createDefault();
357     $purifier = new HTMLPurifier($config);
358     $clean_html = $purifier->purify($dirty_html);
361 If your website is in a different encoding or doctype, use this code:
363 <?php
364     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
366     $config = HTMLPurifier_Config::createDefault();
367     $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding
368     $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
369     $purifier = new HTMLPurifier($config);
371     $clean_html = $purifier->purify($dirty_html);
374     vim: et sw=4 sts=4