INSTALL

   1
   2 Install
   3     How to install HTML Purifier
   4
   5 HTML Purifier is designed to run out of the box,  so actually using the library
   6 is extremely easy. (Although, if you were looking for a step-by-step
   7 installation GUI, you've come to the wrong place!)  The impatient can scroll
   8 down to the bottom of this INSTALL document to see the code, but you really
   9 should make sure a few things are properly done.
  10
  11
  12 1.  Compatibility
  13
  14 HTML Purifier works in both PHP 4 and PHP 5, from PHP 4.3.2 and up. It has no
  15 core dependencies with other libraries.
  16
  17 Optional extensions are iconv (usually installed) and tidy (also common).
  18 If you use UTF-8 and don't plan on pretty-printing HTML, you can get away with
  19 not having either of these extensions.
  20
  21
  22
  23 2.  Including the library
  24
  25 Simply use:
  26
  27     require_once '/path/to/library/HTMLPurifier.auto.php';
  28
  29 ...and you're good to go.  Since HTML Purifier's codebase is fairly
  30 large, I recommend only including HTML Purifier when you need it.
  31
  32 If you don't like your include_path to be fiddled around with, simply set
  33 HTML Purifier's library/ directory to the include path yourself and then:
  34
  35     require_once 'HTMLPurifier.php';
  36
  37 Only the contents in the library/ folder are necessary, so you can remove
  38 everything else when using HTML Purifier in a production environment.
  39
  40
  41
  42 3.  Preparing the proper output environment
  43
  44 HTML Purifier is all about web-standards, so accordingly your webpages should
  45 be standards compliant.  HTML Purifier can deal with these doctypes:
  46
  47 * XHTML 1.0 Transitional (default)
  48 * XHTML 1.0 Strict
  49 * HTML 4.01 Transitional
  50 * HTML 4.01 Strict
  51 * XHTML 1.1 (sans Ruby)
  52
  53 ...and these character encodings:
  54
  55 * UTF-8 (default)
  56 * Any encoding iconv supports (support is crippled for i18n though)
  57
  58 The defaults are there for a reason: they are best-practice choices that
  59 should not be changed lightly.  For those of you in the dark, you can determine
  60 the doctype from this code in your HTML documents:
  61
  62     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  63         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  64
  65 ...and the character encoding from this code:
  66
  67     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
  68
  69 For legacy codebases these declarations may be missing.  If that is the case,
  70 STOP, and read docs/enduser-utf8.html
  71
  72 You may currently be vulnerable to XSS and other security threats, and HTML
  73 Purifier won't be able to fix that.
  74
  75
  76
  77 4. Configuration
  78
  79 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
  80 Purifier needs to be told what to do.  If you answered no to any of these
  81 questions, read on, otherwise, you can skip to the next section (or, if you're
  82 into configuring things just for the heck of it, skip to 4.3).
  83
  84 * Am I using UTF-8?
  85 * Am I using XHTML 1.0 Transitional?
  86
  87 If you answered no to any of these questions, instantiate a configuration
  88 object and read on:
  89
  90     $config = HTMLPurifier_Config::createDefault();
  91
  92
  93
  94 4.1. Setting a different character encoding
  95
  96 You really shouldn't use any other encoding except UTF-8, especially if you
  97 plan to support multilingual websites (read section three for more details).
  98 However, switching to UTF-8 is not always immediately feasible, so we can
  99 adapt.
 100
 101 HTML Purifier uses iconv to support other character encodings, as such,
 102 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 103 HTML Purifier supports with this code:
 104
 105     $config->set('Core', 'Encoding', /* put your encoding here */);
 106
 107 An example usage for Latin-1 websites (the most common encoding for English
 108 websites):
 109
 110     $config->set('Core', 'Encoding', 'ISO-8859-1');
 111
 112 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 113 fact that any character not supported by that encoding will be silently
 114 dropped, EVEN if it is ampersand escaped.  If you want to work around
 115 this, you are welcome to read docs/enduser-utf8.html for a fix,
 116 but please be cognizant of the issues the "solution" creates (for this
 117 reason, I do not include the solution in this document).
 118
 119
 120
 121 4.2. Setting a different doctype
 122
 123 For those of you using HTML 4.01 Transitional, you can disable
 124 XHTML output like this:
 125
 126     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
 127
 128 Other supported doctypes include:
 129
 130     * HTML 4.01 Strict
 131     * HTML 4.01 Transitional
 132     * XHTML 1.0 Strict
 133     * XHTML 1.0 Transitional
 134     * XHTML 1.1
 135
 136
 137
 138 4.3. Other settings
 139
 140 There are more configuration directives which can be read about
 141 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
 142 but they can help out for those of you who like to exert maximum control over
 143 your code.  Some of the more interesting ones are configurable at the
 144 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
 145 for your own system.
 146
 147
 148
 149 5.   Using the code
 150
 151 The interface is mind-numbingly simple:
 152
 153     $purifier = new HTMLPurifier();
 154     $clean_html = $purifier->purify( $dirty_html );
 155
 156 ...or, if you're using the configuration object:
 157
 158     $purifier = new HTMLPurifier($config);
 159     $clean_html = $purifier->purify( $dirty_html );
 160
 161 That's it!  For more examples, check out docs/examples/ (they aren't very
 162 different though).  Also, docs/enduser-slow.html gives advice on what to
 163 do if HTML Purifier is slowing down your application.
 164
 165
 166
 167 6.   Quick install
 168
 169 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
 170 writable by the webserver (see Section 7: Caching below for details).
 171 If your website is in UTF-8 and XHTML Transitional, use this code:
 172
 173 <?php
 174     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 175
 176     $purifier = new HTMLPurifier();
 177     $clean_html = $purifier->purify($dirty_html);
 178 ?>
 179
 180 If your website is in a different encoding or doctype, use this code:
 181
 182 <?php
 183     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 184
 185     $config = HTMLPurifier_Config::createDefault();
 186     $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
 187     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 188     $purifier = new HTMLPurifier($config);
 189
 190     $clean_html = $purifier->purify($dirty_html);
 191 ?>
 192
 193
 194
 195 7. Caching
 196
 197 HTML Purifier generates some cache files (generally one or two) to speed up
 198 its execution. For maximum performance, make sure that
 199 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
 200
 201 If you are in the library/ folder of HTML Purifier, you can set the
 202 appropriate permissions using:
 203
 204     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
 205
 206 If the above command doesn't work, you may need to assign write permissions
 207 to all. This may be necessary if your webserver runs as nobody, but is
 208 not recommended since it means any other user can write files in the
 209 directory. Use:
 210
 211     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
 212
 213 You can also chmod files via your FTP client; this option
 214 is usually accessible by right clicking the corresponding directory and
 215 then selecting "chmod" or "file permissions".
 216
 217 Starting with 2.0.1, HTML Purifier will generate friendly error messages
 218 that will tell you exactly what you have to chmod the directory to, if in doubt,
 219 follow its advice.
 220
 221 If you are unable or unwilling to give write permissions to the cache
 222 directory, you can either disable the cache (and suffer a performance
 223 hit):
 224
 225     $config->set('Core', 'DefinitionCache', null);
 226
 227 Or move the cache directory somewhere else (no trailing slash):
 228
 229     $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
 230