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 reading this entire
  11 document--most of the other documentation assumes that you are familiar
  12 with these contents.
  13
  14
  15 ---------------------------------------------------------------------------
  16 1.  Compatibility
  17
  18 HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.5 and
  19 up. It has no core dependencies with other libraries. PHP
  20 4 support was deprecated on December 31, 2007 with HTML Purifier 3.0.0.
  21 HTML Purifier is not compatible with zend.ze1_compatibility_mode.
  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     * bcmath : Used for unit conversion and imagecrash protection
  27     * tidy   : Used for pretty-printing HTML
  28
  29
  30 ---------------------------------------------------------------------------
  31 2.  Reconnaissance
  32
  33 A big plus of HTML Purifier is its inerrant support of standards, so
  34 your web-pages should be standards-compliant.  (They should also use
  35 semantic markup, but that's another issue altogether, one HTML Purifier
  36 cannot fix without reading your mind.)
  37
  38 HTML Purifier can process these doctypes:
  39
  40 * XHTML 1.0 Transitional (default)
  41 * XHTML 1.0 Strict
  42 * HTML 4.01 Transitional
  43 * HTML 4.01 Strict
  44 * XHTML 1.1
  45
  46 ...and these character encodings:
  47
  48 * UTF-8 (default)
  49 * Any encoding iconv supports (with crippled internationalization support)
  50
  51 These defaults reflect what my choices would be if I were authoring an
  52 HTML document, however, what you choose depends on the nature of your
  53 codebase.  If you don't know what doctype you are using, you can determine
  54 the doctype from this identifier at the top of your source code:
  55
  56     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  57         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  58
  59 ...and the character encoding from this code:
  60
  61     <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
  62
  63 If the character encoding declaration is missing, STOP NOW, and
  64 read 'docs/enduser-utf8.html' (web accessible at
  65 http://htmlpurifier.org/docs/enduser-utf8.html).  In fact, even if it is
  66 present, read this document anyway, as many websites specify their
  67 document's character encoding incorrectly.
  68
  69
  70 ---------------------------------------------------------------------------
  71 3.  Including the library
  72
  73 The procedure is quite simple:
  74
  75     require_once '/path/to/library/HTMLPurifier.auto.php';
  76
  77 This will setup an autoloader, so the library's files are only included
  78 when you use them.
  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 If you installed HTML Purifier via PEAR, all you need to do is:
  84
  85     require_once 'HTMLPurifier.auto.php';
  86
  87 Please note that the usual PEAR practice of including just the classes you
  88 want will not work with HTML Purifier's autoloading scheme.
  89
  90 Advanced users, read on; other users can skip to section 4.
  91
  92 Autoload compatibility
  93 ----------------------
  94
  95     HTML Purifier attempts to be as smart as possible when registering an
  96     autoloader, but there are some cases where you will need to change
  97     your own code to accomodate HTML Purifier. These are those cases:
  98
  99     PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
 100         Because spl_autoload_register() doesn't exist in early versions
 101         of PHP 5, HTML Purifier has no way of adding itself to the autoload
 102         stack. Modify your __autoload function to test
 103         HTMLPurifier_Bootstrap::autoload($class)
 104
 105         For example, suppose your autoload function looks like this:
 106
 107             function __autoload($class) {
 108                 require str_replace('_', '/', $class) . '.php';
 109                 return true;
 110             }
 111
 112         A modified version with HTML Purifier would look like this:
 113
 114             function __autoload($class) {
 115                 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
 116                 require str_replace('_', '/', $class) . '.php';
 117                 return true;
 118             }
 119
 120         Note that there *is* some custom behavior in our autoloader; the
 121         original autoloader in our example would work for 99% of the time,
 122         but would fail when including language files.
 123
 124     AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
 125         spl_autoload_register() has the curious behavior of disabling
 126         the existing __autoload() handler. Users need to explicitly
 127         spl_autoload_register('__autoload'). Because we use SPL when it
 128         is available, __autoload() will ALWAYS be disabled. If __autoload()
 129         is declared before HTML Purifier is loaded, this is not a problem:
 130         HTML Purifier will register the function for you. But if it is
 131         declared afterwards, it will mysteriously not work. This
 132         snippet of code (after your autoloader is defined) will fix it:
 133
 134             spl_autoload_register('__autoload')
 135
 136     Users should also be on guard if they use a version of PHP previous
 137     to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
 138     for you, which can collide with an autoloader that was added by *you*
 139     later.
 140
 141
 142 For better performance
 143 ----------------------
 144
 145     Opcode caches, which greatly speed up PHP initialization for scripts
 146     with large amounts of code (HTML Purifier included), don't like
 147     autoloaders. We offer an include file that includes all of HTML Purifier's
 148     files in one go in an opcode cache friendly manner:
 149
 150         // If /path/to/library isn't already in your include path, uncomment
 151         // the below line:
 152         // require '/path/to/library/HTMLPurifier.path.php';
 153
 154         require 'HTMLPurifier.includes.php';
 155
 156     Optional components still need to be included--you'll know if you try to
 157     use a feature and you get a class doesn't exists error! The autoloader
 158     can be used in conjunction with this approach to catch classes that are
 159     missing. Simply add this afterwards:
 160
 161         require 'HTMLPurifier.autoload.php';
 162
 163 Standalone version
 164 ------------------
 165
 166     HTML Purifier has a standalone distribution; you can also generate
 167     a standalone file from the full version by running the script
 168     maintenance/generate-standalone.php . The standalone version has the
 169     benefit of having most of its code in one file, so parsing is much
 170     faster and the library is easier to manage.
 171
 172     If HTMLPurifier.standalone.php exists in the library directory, you
 173     can use it like this:
 174
 175         require '/path/to/HTMLPurifier.standalone.php';
 176
 177     This is equivalent to including HTMLPurifier.includes.php, except that
 178     the contents of standalone/ will be added to your path. To override this
 179     behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
 180     be found (usually, this will be one directory up, the "true" library
 181     directory in full distributions). Don't forget to set your path too!
 182
 183     The autoloader can be added to the end to ensure the classes are
 184     loaded when necessary; otherwise you can manually include them.
 185     To use the autoloader, use this:
 186
 187         require 'HTMLPurifier.autoload.php';
 188
 189 For advanced users
 190 ------------------
 191
 192     HTMLPurifier.auto.php performs a number of operations that can be done
 193     individually. These are:
 194
 195         HTMLPurifier.path.php
 196             Puts /path/to/library in the include path. For high performance,
 197             this should be done in php.ini.
 198
 199         HTMLPurifier.autoload.php
 200             Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
 201
 202     You can do these operations by yourself--in fact, you must modify your own
 203     autoload handler if you are using a version of PHP earlier than PHP 5.1.2
 204     (See "Autoload compatibility" above).
 205
 206
 207 ---------------------------------------------------------------------------
 208 4. Configuration
 209
 210 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
 211 Purifier needs to be told what to do.  If you answer no to any of these
 212 questions, read on; otherwise, you can skip to the next section (or, if you're
 213 into configuring things just for the heck of it, skip to 4.3).
 214
 215 * Am I using UTF-8?
 216 * Am I using XHTML 1.0 Transitional?
 217
 218 If you answered no to any of these questions, instantiate a configuration
 219 object and read on:
 220
 221     $config = HTMLPurifier_Config::createDefault();
 222
 223
 224 4.1. Setting a different character encoding
 225
 226 You really shouldn't use any other encoding except UTF-8, especially if you
 227 plan to support multilingual websites (read section three for more details).
 228 However, switching to UTF-8 is not always immediately feasible, so we can
 229 adapt.
 230
 231 HTML Purifier uses iconv to support other character encodings, as such,
 232 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 233 HTML Purifier supports with this code:
 234
 235     $config->set('Core.Encoding', /* put your encoding here */);
 236
 237 An example usage for Latin-1 websites (the most common encoding for English
 238 websites):
 239
 240     $config->set('Core.Encoding', 'ISO-8859-1');
 241
 242 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 243 fact that any character not supported by that encoding will be silently
 244 dropped, EVEN if it is ampersand escaped.  If you want to work around
 245 this, you are welcome to read docs/enduser-utf8.html for a fix,
 246 but please be cognizant of the issues the "solution" creates (for this
 247 reason, I do not include the solution in this document).
 248
 249
 250 4.2. Setting a different doctype
 251
 252 For those of you using HTML 4.01 Transitional, you can disable
 253 XHTML output like this:
 254
 255     $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
 256
 257 Other supported doctypes include:
 258
 259     * HTML 4.01 Strict
 260     * HTML 4.01 Transitional
 261     * XHTML 1.0 Strict
 262     * XHTML 1.0 Transitional
 263     * XHTML 1.1
 264
 265
 266 4.3. Other settings
 267
 268 There are more configuration directives which can be read about
 269 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
 270 but they can help out for those of you who like to exert maximum control over
 271 your code.  Some of the more interesting ones are configurable at the
 272 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
 273 for your own system.
 274
 275 For example, you can fine tune allowed elements and attributes, convert
 276 relative URLs to absolute ones, and even autoparagraph input text! These
 277 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
 278 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
 279 translates to:
 280
 281     $config->set('Namespace.Directive', $value);
 282
 283 E.g.
 284
 285     $config->set('HTML.Allowed', 'p,b,a[href],i');
 286     $config->set('URI.Base', 'http://www.example.com');
 287     $config->set('URI.MakeAbsolute', true);
 288     $config->set('AutoFormat.AutoParagraph', true);
 289
 290
 291 ---------------------------------------------------------------------------
 292 5. Caching
 293
 294 HTML Purifier generates some cache files (generally one or two) to speed up
 295 its execution. For maximum performance, make sure that
 296 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
 297
 298 If you are in the library/ folder of HTML Purifier, you can set the
 299 appropriate permissions using:
 300
 301     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
 302
 303 If the above command doesn't work, you may need to assign write permissions
 304 to all. This may be necessary if your webserver runs as nobody, but is
 305 not recommended since it means any other user can write files in the
 306 directory. Use:
 307
 308     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
 309
 310 You can also chmod files via your FTP client; this option
 311 is usually accessible by right clicking the corresponding directory and
 312 then selecting "chmod" or "file permissions".
 313
 314 Starting with 2.0.1, HTML Purifier will generate friendly error messages
 315 that will tell you exactly what you have to chmod the directory to, if in doubt,
 316 follow its advice.
 317
 318 If you are unable or unwilling to give write permissions to the cache
 319 directory, you can either disable the cache (and suffer a performance
 320 hit):
 321
 322     $config->set('Core.DefinitionCache', null);
 323
 324 Or move the cache directory somewhere else (no trailing slash):
 325
 326     $config->set('Cache.SerializerPath', '/home/user/absolute/path');
 327
 328
 329 ---------------------------------------------------------------------------
 330 6.   Using the code
 331
 332 The interface is mind-numbingly simple:
 333
 334     $purifier = new HTMLPurifier();
 335     $clean_html = $purifier->purify( $dirty_html );
 336
 337 ...or, if you're using the configuration object:
 338
 339     $purifier = new HTMLPurifier($config);
 340     $clean_html = $purifier->purify( $dirty_html );
 341
 342 That's it!  For more examples, check out docs/examples/ (they aren't very
 343 different though).  Also, docs/enduser-slow.html gives advice on what to
 344 do if HTML Purifier is slowing down your application.
 345
 346
 347 ---------------------------------------------------------------------------
 348 7.   Quick install
 349
 350 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
 351 writable by the webserver (see Section 5: Caching above for details).
 352 If your website is in UTF-8 and XHTML Transitional, use this code:
 353
 354 <?php
 355     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 356
 357     $purifier = new HTMLPurifier();
 358     $clean_html = $purifier->purify($dirty_html);
 359 ?>
 360
 361 If your website is in a different encoding or doctype, use this code:
 362
 363 <?php
 364     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 365
 366     $config = HTMLPurifier_Config::createDefault();
 367     $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding
 368     $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 369     $purifier = new HTMLPurifier($config);
 370
 371     $clean_html = $purifier->purify($dirty_html);
 372 ?>
 373
 374     vim: et sw=4 sts=4