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
   6 library is extremely easy.  (Although... if you were looking for a
   7 step-by-step installation GUI, you've downloaded the wrong software!)
   8
   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 performing some
  11 basic sanity checks to get the most out of this library.
  12
  13 ---------------------------------------------------------------------------
  14 1.  Compatibility
  15
  16 HTML Purifier works in both PHP 4 and PHP 5, from PHP 4.3.2 and up. It has
  17 no core dependencies with other libraries.  PHP 4 support will be
  18 deprecated on December 31, 2007, at which time only essential security
  19 fixes will be issued for the PHP 4 version until August 8, 2008.
  20
  21 These optional extensions can enhance the capabilities of HTML Purifier:
  22
  23     * iconv : Converts text to and from non-UTF-8 encodings
  24     * tidy  : Used for pretty-printing HTML
  25
  26 ---------------------------------------------------------------------------
  27 2.  Reconnaissance
  28
  29 A big plus of HTML Purifier is its inerrant support of standards, so
  30 your web-pages should be standards-compliant.  (They should also use
  31 semantic markup, but that's another issue altogether, one HTML Purifier
  32 cannot fix without reading your mind.)
  33
  34 HTML Purifier can process these doctypes:
  35
  36 * XHTML 1.0 Transitional (default)
  37 * XHTML 1.0 Strict
  38 * HTML 4.01 Transitional
  39 * HTML 4.01 Strict
  40 * XHTML 1.1
  41
  42 ...and these character encodings:
  43
  44 * UTF-8 (default)
  45 * Any encoding iconv supports (but crippled internationalization support)
  46
  47 These defaults reflect what my choices where be if I were authoring an
  48 HTML document, however, what you choose depends on the nature of your
  49 codebase.  If you don't know what doctype you are using, you can determine
  50 the doctype from this identifier at the top of your source code:
  51
  52     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  53         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  54
  55 ...and the character encoding from this code:
  56
  57     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
  58
  59 If the character encoding declaration is missing, STOP NOW, and
  60 read 'docs/enduser-utf8.html' (web accessible at
  61 http://htmlpurifier.org/docs/enduser-utf8.html).  In fact, even if it is
  62 present, read that anyway: most websites specify character encoding
  63 incorrectly.
  64
  65 ---------------------------------------------------------------------------
  66 3.  Including the library
  67
  68 The procedure is quite simple:
  69
  70     require_once '/path/to/library/HTMLPurifier.auto.php';
  71
  72 I recommend only including HTML Purifier when you need it, because that
  73 call represents the inclusion of a lot of PHP files.
  74
  75 If you don't like your include_path to be fiddled around with, simply set
  76 HTML Purifier's library/ directory to the include path yourself and then:
  77
  78     require_once 'HTMLPurifier.php';
  79
  80 Only the contents in the library/ folder are necessary, so you can remove
  81 everything else when using HTML Purifier in a production environment.
  82
  83
  84 ---------------------------------------------------------------------------
  85 4. Configuration
  86
  87 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
  88 Purifier needs to be told what to do.  If you answered no to any of these
  89 questions, read on, otherwise, you can skip to the next section (or, if you're
  90 into configuring things just for the heck of it, skip to 4.3).
  91
  92 * Am I using UTF-8?
  93 * Am I using XHTML 1.0 Transitional?
  94
  95 If you answered no to any of these questions, instantiate a configuration
  96 object and read on:
  97
  98     $config = HTMLPurifier_Config::createDefault();
  99
 100
 101
 102 4.1. Setting a different character encoding
 103
 104 You really shouldn't use any other encoding except UTF-8, especially if you
 105 plan to support multilingual websites (read section three for more details).
 106 However, switching to UTF-8 is not always immediately feasible, so we can
 107 adapt.
 108
 109 HTML Purifier uses iconv to support other character encodings, as such,
 110 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 111 HTML Purifier supports with this code:
 112
 113     $config->set('Core', 'Encoding', /* put your encoding here */);
 114
 115 An example usage for Latin-1 websites (the most common encoding for English
 116 websites):
 117
 118     $config->set('Core', 'Encoding', 'ISO-8859-1');
 119
 120 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 121 fact that any character not supported by that encoding will be silently
 122 dropped, EVEN if it is ampersand escaped.  If you want to work around
 123 this, you are welcome to read docs/enduser-utf8.html for a fix,
 124 but please be cognizant of the issues the "solution" creates (for this
 125 reason, I do not include the solution in this document).
 126
 127
 128
 129 4.2. Setting a different doctype
 130
 131 For those of you using HTML 4.01 Transitional, you can disable
 132 XHTML output like this:
 133
 134     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
 135
 136 Other supported doctypes include:
 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.  Some of the more interesting ones are configurable at the
 152 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
 153 for your own system.
 154
 155
 156 ---------------------------------------------------------------------------
 157 5.   Using the code
 158
 159 The interface is mind-numbingly simple:
 160
 161     $purifier = new HTMLPurifier();
 162     $clean_html = $purifier->purify( $dirty_html );
 163
 164 ...or, if you're using the configuration object:
 165
 166     $purifier = new HTMLPurifier($config);
 167     $clean_html = $purifier->purify( $dirty_html );
 168
 169 That's it!  For more examples, check out docs/examples/ (they aren't very
 170 different though).  Also, docs/enduser-slow.html gives advice on what to
 171 do if HTML Purifier is slowing down your application.
 172
 173
 174 ---------------------------------------------------------------------------
 175 6.   Quick install
 176
 177 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
 178 writable by the webserver (see Section 7: Caching below for details).
 179 If your website is in UTF-8 and XHTML Transitional, use this code:
 180
 181 <?php
 182     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 183
 184     $purifier = new HTMLPurifier();
 185     $clean_html = $purifier->purify($dirty_html);
 186 ?>
 187
 188 If your website is in a different encoding or doctype, use this code:
 189
 190 <?php
 191     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 192
 193     $config = HTMLPurifier_Config::createDefault();
 194     $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
 195     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 196     $purifier = new HTMLPurifier($config);
 197
 198     $clean_html = $purifier->purify($dirty_html);
 199 ?>
 200
 201
 202 ---------------------------------------------------------------------------
 203 7. Caching
 204
 205 HTML Purifier generates some cache files (generally one or two) to speed up
 206 its execution. For maximum performance, make sure that
 207 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
 208
 209 If you are in the library/ folder of HTML Purifier, you can set the
 210 appropriate permissions using:
 211
 212     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
 213
 214 If the above command doesn't work, you may need to assign write permissions
 215 to all. This may be necessary if your webserver runs as nobody, but is
 216 not recommended since it means any other user can write files in the
 217 directory. Use:
 218
 219     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
 220
 221 You can also chmod files via your FTP client; this option
 222 is usually accessible by right clicking the corresponding directory and
 223 then selecting "chmod" or "file permissions".
 224
 225 Starting with 2.0.1, HTML Purifier will generate friendly error messages
 226 that will tell you exactly what you have to chmod the directory to, if in doubt,
 227 follow its advice.
 228
 229 If you are unable or unwilling to give write permissions to the cache
 230 directory, you can either disable the cache (and suffer a performance
 231 hit):
 232
 233     $config->set('Core', 'DefinitionCache', null);
 234
 235 Or move the cache directory somewhere else (no trailing slash):
 236
 237     $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
 238