INSTALL

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