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