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