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