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 WARNING: Currently, the HTMLPurifier.auto.php file is broken due to our
  75 configuration setup. Once ConfigSchema is migrated outside of PHP files,
  76 this information will be correct.
  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 For better performance
  89 ----------------------
  90
  91     Opcode caches, which greatly speed up PHP initialization for scripts
  92     with large amounts of code (HTML Purifier included), don't like
  93     autoloaders. We offer an include file that includes all of HTML Purifier's
  94     files in one go in an opcode cache friendly manner:
  95
  96         // If /path/to/library isn't already in your include path, uncomment
  97         // the below line:
  98         // set_include_path( '/path/to/library' . PATH_SEPARATOR . get_include_path() );
  99
 100         require 'HTMLPurifier.includes.php';
 101
 102     Optional components still need to be included--you'll know if you try to
 103     use a feature and you get a class doesn't exists error! The autoloader
 104     can be used in conjunction with this approach to catch
 105
 106 For advanced users
 107 ------------------
 108
 109     HTMLPurifier.auto.php performs a number of operations that can be done
 110     individually. These are:
 111
 112         * Puts /path/to/library in the include path,
 113         * Registers an autoload handler with HTMLPurifier.autoload.php
 114           (depending on your version of PHP, this means using
 115           spl_autoload_register or defining an __autoload function)
 116
 117     You can do these operations by yourself--in fact, you must modify your own
 118     autoload handler if you are using a version of PHP earlier than PHP 5.1.2.
 119     HTML Purifier's autoload handler is HTMLPurifier_Bootstrap::autoload($class)
 120     (so be sure to include HTMLPurifier/Bootstrap.php first.)
 121
 122
 123 ---------------------------------------------------------------------------
 124 4. Configuration
 125
 126 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
 127 Purifier needs to be told what to do.  If you answered no to any of these
 128 questions, read on, otherwise, you can skip to the next section (or, if you're
 129 into configuring things just for the heck of it, skip to 4.3).
 130
 131 * Am I using UTF-8?
 132 * Am I using XHTML 1.0 Transitional?
 133
 134 If you answered no to any of these questions, instantiate a configuration
 135 object and read on:
 136
 137     $config = HTMLPurifier_Config::createDefault();
 138
 139
 140 4.1. Setting a different character encoding
 141
 142 You really shouldn't use any other encoding except UTF-8, especially if you
 143 plan to support multilingual websites (read section three for more details).
 144 However, switching to UTF-8 is not always immediately feasible, so we can
 145 adapt.
 146
 147 HTML Purifier uses iconv to support other character encodings, as such,
 148 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 149 HTML Purifier supports with this code:
 150
 151     $config->set('Core', 'Encoding', /* put your encoding here */);
 152
 153 An example usage for Latin-1 websites (the most common encoding for English
 154 websites):
 155
 156     $config->set('Core', 'Encoding', 'ISO-8859-1');
 157
 158 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 159 fact that any character not supported by that encoding will be silently
 160 dropped, EVEN if it is ampersand escaped.  If you want to work around
 161 this, you are welcome to read docs/enduser-utf8.html for a fix,
 162 but please be cognizant of the issues the "solution" creates (for this
 163 reason, I do not include the solution in this document).
 164
 165
 166 4.2. Setting a different doctype
 167
 168 For those of you using HTML 4.01 Transitional, you can disable
 169 XHTML output like this:
 170
 171     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
 172
 173 Other supported doctypes include:
 174
 175     * HTML 4.01 Strict
 176     * HTML 4.01 Transitional
 177     * XHTML 1.0 Strict
 178     * XHTML 1.0 Transitional
 179     * XHTML 1.1
 180
 181
 182 4.3. Other settings
 183
 184 There are more configuration directives which can be read about
 185 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
 186 but they can help out for those of you who like to exert maximum control over
 187 your code.  Some of the more interesting ones are configurable at the
 188 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
 189 for your own system.
 190
 191 For example, you can fine tune allowed elements and attributes, convert
 192 relative URLs to absolute ones, and even autoparagraph input text! These
 193 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
 194 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
 195 translates to:
 196
 197     $config->set('Namespace', 'Directive', $value);
 198
 199 E.g.
 200
 201     $config->set('HTML', 'Allowed', 'p,b,a[href],i');
 202     $config->set('URI', 'Base', 'http://www.example.com');
 203     $config->set('URI', 'MakeAbsolute', true);
 204     $config->set('AutoFormat', 'AutoParagraph', true);
 205
 206
 207 ---------------------------------------------------------------------------
 208 5. Caching
 209
 210 HTML Purifier generates some cache files (generally one or two) to speed up
 211 its execution. For maximum performance, make sure that
 212 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
 213
 214 If you are in the library/ folder of HTML Purifier, you can set the
 215 appropriate permissions using:
 216
 217     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
 218
 219 If the above command doesn't work, you may need to assign write permissions
 220 to all. This may be necessary if your webserver runs as nobody, but is
 221 not recommended since it means any other user can write files in the
 222 directory. Use:
 223
 224     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
 225
 226 You can also chmod files via your FTP client; this option
 227 is usually accessible by right clicking the corresponding directory and
 228 then selecting "chmod" or "file permissions".
 229
 230 Starting with 2.0.1, HTML Purifier will generate friendly error messages
 231 that will tell you exactly what you have to chmod the directory to, if in doubt,
 232 follow its advice.
 233
 234 If you are unable or unwilling to give write permissions to the cache
 235 directory, you can either disable the cache (and suffer a performance
 236 hit):
 237
 238     $config->set('Core', 'DefinitionCache', null);
 239
 240 Or move the cache directory somewhere else (no trailing slash):
 241
 242     $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
 243
 244
 245 ---------------------------------------------------------------------------
 246 6.   Using the code
 247
 248 The interface is mind-numbingly simple:
 249
 250     $purifier = new HTMLPurifier();
 251     $clean_html = $purifier->purify( $dirty_html );
 252
 253 ...or, if you're using the configuration object:
 254
 255     $purifier = new HTMLPurifier($config);
 256     $clean_html = $purifier->purify( $dirty_html );
 257
 258 That's it!  For more examples, check out docs/examples/ (they aren't very
 259 different though).  Also, docs/enduser-slow.html gives advice on what to
 260 do if HTML Purifier is slowing down your application.
 261
 262
 263 ---------------------------------------------------------------------------
 264 7.   Quick install
 265
 266 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
 267 writable by the webserver (see Section 5: Caching above for details).
 268 If your website is in UTF-8 and XHTML Transitional, use this code:
 269
 270 <?php
 271     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 272
 273     $purifier = new HTMLPurifier();
 274     $clean_html = $purifier->purify($dirty_html);
 275 ?>
 276
 277 If your website is in a different encoding or doctype, use this code:
 278
 279 <?php
 280     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 281
 282     $config = HTMLPurifier_Config::createDefault();
 283     $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
 284     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 285     $purifier = new HTMLPurifier($config);
 286
 287     $clean_html = $purifier->purify($dirty_html);
 288 ?>
 289