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