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 workaround,
 116 but please be cognizant of the issues the "solution" creates.
 117
 118
 119
 120 4.2. Setting a different doctype
 121
 122 For those of you using HTML 4.01 Transitional, you can disable
 123 XHTML output like this:
 124
 125     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
 126
 127 Other supported doctypes include:
 128
 129     * HTML 4.01 Strict
 130     * HTML 4.01 Transitional
 131     * XHTML 1.0 Strict
 132     * XHTML 1.0 Transitional
 133     * XHTML 1.1
 134
 135
 136
 137 4.3. Other settings
 138
 139 There are more configuration directives which can be read about
 140 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
 141 but they can help out for those of you who like to exert maximum control over
 142 your code.
 143
 144
 145
 146 5.   Using the code
 147
 148 The interface is mind-numbingly simple:
 149
 150     $purifier = new HTMLPurifier();
 151     $clean_html = $purifier->purify( $dirty_html );
 152
 153 ...or, if you're using the configuration object:
 154
 155     $purifier = new HTMLPurifier($config);
 156     $clean_html = $purifier->purify( $dirty_html );
 157
 158 That's it!  For more examples, check out docs/examples/ (they aren't very
 159 different though).  Also, SLOW gives advice on what to do if HTML Purifier
 160 is slowing down your application.
 161
 162
 163
 164 6.   Quick install
 165
 166 If your website is in UTF-8 and XHTML Transitional, use this code:
 167
 168 <?php
 169     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 170
 171     $purifier = new HTMLPurifier();
 172     $clean_html = $purifier->purify($dirty_html);
 173 ?>
 174
 175 If your website is in a different encoding or doctype, use this code:
 176
 177 <?php
 178     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 179
 180     $config = HTMLPurifier_Config::createDefault();
 181     $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
 182     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 183     $purifier = new HTMLPurifier($config);
 184
 185     $clean_html = $purifier->purify($dirty_html);
 186 ?>
 187
 188
 189
 190 7. Caching
 191
 192 HTML Purifier generates some cache files to speed up its execution. For
 193 maximum performance, make sure that library/HTMLPurifier/DefinitionCache/Serializer
 194 is writeable by the webserver.