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 Todo: Convert to using the array syntax for configuration.
  12
  13
  14 1.  Compatibility
  15
  16 HTML Purifier works in both PHP 4 and PHP 5, from PHP 4.3.9 and up. It has no
  17 core dependencies with other libraries. (Whoopee!)
  18
  19 Optional extensions are iconv (usually installed) and tidy (also common).
  20 If you use UTF-8 and don't plan on pretty-printing HTML, you can get away with
  21 not having either of these extensions.
  22
  23
  24
  25 2.  Including the library
  26
  27 Simply use:
  28
  29     require_once '/path/to/library/HTMLPurifier.auto.php';
  30
  31 ...and you're good to go.  Since HTML Purifier's codebase is fairly
  32 large, I recommend only including HTML Purifier when you need it.
  33
  34 If you don't like your include_path to be fiddled around with, simply set
  35 HTML Purifier's library/ directory to the include path yourself and then:
  36
  37     require_once 'HTMLPurifier.php';
  38
  39 Only the contents in the library/ folder are necessary, so you can remove
  40 everything else when using HTML Purifier in a production environment.
  41
  42
  43
  44 3.  Preparing the proper output environment
  45
  46 HTML Purifier is all about web-standards, so accordingly your webpages should
  47 be standards compliant.  HTML Purifier can deal with these doctypes:
  48
  49 * XHTML 1.0 Transitional (default)
  50 * HTML 4.01 Transitional
  51
  52 ...and these character encodings:
  53
  54 * UTF-8 (default)
  55 * Any encoding iconv supports (support is crippled for i18n though)
  56
  57 The defaults are there for a reason: they are best-practice choices that
  58 should not be changed lightly.  For those of you in the dark, you can determine
  59 the doctype from this code in your HTML documents:
  60
  61     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  62         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  63
  64 ...and the character encoding from this code:
  65
  66     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
  67
  68 For legacy codebases these declarations may be missing.  If that is the case,
  69 STOP, and read up on character encodings and doctypes (in that order).  Here
  70 are some links:
  71
  72 * http://www.joelonsoftware.com/articles/Unicode.html
  73 * http://alistapart.com/stories/doctype/
  74
  75 You may currently be vulnerable to XSS and other security threats, and HTML
  76 Purifier won't be able to fix that.
  77
  78
  79
  80 4. Configuration
  81
  82 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
  83 Purifier needs to be told what to do.  If you answered no to any of these
  84 questions, read on, otherwise, you can skip to the next section (or, if you're
  85 into configuring things just for the heck of it, skip to 4.3).
  86
  87 * Am I using UTF-8?
  88 * Am I using XHTML 1.0 Transitional?
  89
  90 If you answered yes to any of these questions, instantiate a configuration
  91 object and read on:
  92
  93     $config = HTMLPurifier_Config::createDefault();
  94
  95
  96
  97 4.1. Setting a different character encoding
  98
  99 You really shouldn't use any other encoding except UTF-8, especially if you
 100 plan to support multilingual websites (read section three for more details).
 101 However, switching to UTF-8 is not always immediately feasible, so we can
 102 adapt.
 103
 104 HTML Purifier uses iconv to support other character encodings, as such,
 105 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 106 HTML Purifier supports with this code:
 107
 108     $config->set('Core', 'Encoding', /* put your encoding here */);
 109
 110 An example usage for Latin-1 websites (the most common encoding for English
 111 websites):
 112
 113     $config->set('Core', 'Encoding', 'ISO-8859-1');
 114
 115 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 116 fact that any character not supported by that encoding will be silently
 117 dropped, EVEN if it is ampersand escaped.  This is a current limitation of
 118 HTML Purifier that we are NOT actively working to fix.  Patches are welcome,
 119 but there are so many other gotchas and problems in I18N for non-Unicode
 120 encodings that this functionality is low priority.  See
 121 <http://ppewww.ph.gla.ac.uk/~flavell/charset/form-i18n.html> for a more
 122 detailed lowdown on the topic.
 123
 124
 125
 126 4.2. Setting a different doctype
 127
 128 For those of you stuck using HTML 4.01 Transitional, you can disable
 129 XHTML output like this:
 130
 131     $config->set('Core', 'XHTML', false);
 132
 133 I recommend that you use XHTML, although not as much as I recommend UTF-8.  If
 134 your HTML 4.01 page validates, good for you!
 135
 136 Currently, we can only guarantee transitional-complaint output, future
 137 versions will also allow strict-compliant output.
 138
 139
 140
 141 4.3. Other settings
 142
 143 There are more configuration directives which can be read about
 144 here: <http://hp.jpsband.org/live/configdoc/plain.html>  They're a bit boring,
 145 but they can help out for those of you who like to exert maximum control over
 146 your code.
 147
 148
 149
 150 5.   Using the code
 151
 152 The interface is mind-numbingly simple:
 153
 154     $purifier = new HTMLPurifier();
 155     $clean_html = $purifier->purify( $dirty_html );
 156
 157 ...or, if you're using the configuration object:
 158
 159     $purifier = new HTMLPurifier($config);
 160     $clean_html = $purifier->purify( $dirty_html );
 161
 162 That's it!  For more examples, check out docs/examples/ (they aren't very
 163 different though).  Also, SLOW gives advice on what to do if HTML Purifier
 164 is slowing down your application.
 165
 166
 167
 168 6.   Quick install
 169
 170 If your website is in UTF-8 and XHTML Transitional, use this code:
 171
 172 <?php
 173     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 174
 175     $purifier = new HTMLPurifier();
 176     $clean_html = $purifier->purify($dirty_html);
 177 ?>
 178
 179 If your website is in a different encoding or doctype, use this code:
 180
 181 <?php
 182     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 183
 184     $config = HTMLPurifier_Config::createDefault();
 185     $config->set('Core', 'Encoding', 'ISO-8859-1'); //replace with your encoding
 186     $config->set('Core', 'XHTML', true); //replace with false if HTML 4.01
 187     $purifier = new HTMLPurifier($config);
 188
 189     $clean_html = $purifier->purify($dirty_html);
 190 ?>