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 performing some
  11 basic sanity checks to get the most out of this library.
  12
  13
  14 ---------------------------------------------------------------------------
  15 1.  Compatibility
  16
  17 HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.0 and
  18 up (see tests/multitest.php for the specific versions that are being
  19 actively tested). 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     * 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 where 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 most websites specify character
  67 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 I recommend only including HTML Purifier when you need it, because that
  78 call represents the inclusion of a lot of PHP files which constitute
  79 the bulk of HTML Purifier's memory usage.
  80
  81 If you don't like your include_path to be fiddled around with, simply set
  82 HTML Purifier's library/ directory to the include path yourself and then:
  83
  84     require_once 'HTMLPurifier.php';
  85
  86 Only the contents in the library/ folder are necessary, so you can remove
  87 everything else when using HTML Purifier in a production environment.
  88
  89
  90 ---------------------------------------------------------------------------
  91 4. Configuration
  92
  93 HTML Purifier is designed to run out-of-the-box, but occasionally HTML
  94 Purifier needs to be told what to do.  If you answered no to any of these
  95 questions, read on, otherwise, you can skip to the next section (or, if you're
  96 into configuring things just for the heck of it, skip to 4.3).
  97
  98 * Am I using UTF-8?
  99 * Am I using XHTML 1.0 Transitional?
 100
 101 If you answered no to any of these questions, instantiate a configuration
 102 object and read on:
 103
 104     $config = HTMLPurifier_Config::createDefault();
 105
 106
 107 4.1. Setting a different character encoding
 108
 109 You really shouldn't use any other encoding except UTF-8, especially if you
 110 plan to support multilingual websites (read section three for more details).
 111 However, switching to UTF-8 is not always immediately feasible, so we can
 112 adapt.
 113
 114 HTML Purifier uses iconv to support other character encodings, as such,
 115 any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
 116 HTML Purifier supports with this code:
 117
 118     $config->set('Core', 'Encoding', /* put your encoding here */);
 119
 120 An example usage for Latin-1 websites (the most common encoding for English
 121 websites):
 122
 123     $config->set('Core', 'Encoding', 'ISO-8859-1');
 124
 125 Note that HTML Purifier's support for non-Unicode encodings is crippled by the
 126 fact that any character not supported by that encoding will be silently
 127 dropped, EVEN if it is ampersand escaped.  If you want to work around
 128 this, you are welcome to read docs/enduser-utf8.html for a fix,
 129 but please be cognizant of the issues the "solution" creates (for this
 130 reason, I do not include the solution in this document).
 131
 132
 133 4.2. Setting a different doctype
 134
 135 For those of you using HTML 4.01 Transitional, you can disable
 136 XHTML output like this:
 137
 138     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
 139
 140 Other supported doctypes include:
 141
 142     * HTML 4.01 Strict
 143     * HTML 4.01 Transitional
 144     * XHTML 1.0 Strict
 145     * XHTML 1.0 Transitional
 146     * XHTML 1.1
 147
 148
 149 4.3. Other settings
 150
 151 There are more configuration directives which can be read about
 152 here: <http://htmlpurifier.org/live/configdoc/plain.html>  They're a bit boring,
 153 but they can help out for those of you who like to exert maximum control over
 154 your code.  Some of the more interesting ones are configurable at the
 155 demo <http://htmlpurifier.org/demo.php> and are well worth looking into
 156 for your own system.
 157
 158 For example, you can fine tune allowed elements and attributes, convert
 159 relative URLs to absolute ones, and even autoparagraph input text! These
 160 are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
 161 %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
 162 translates to:
 163
 164     $config->set('Namespace', 'Directive', $value);
 165
 166 E.g.
 167
 168     $config->set('HTML', 'Allowed', 'p,b,a[href],i');
 169     $config->set('URI', 'Base', 'http://www.example.com');
 170     $config->set('URI', 'MakeAbsolute', true);
 171     $config->set('AutoFormat', 'AutoParagraph', true);
 172
 173
 174 ---------------------------------------------------------------------------
 175 5. Caching
 176
 177 HTML Purifier generates some cache files (generally one or two) to speed up
 178 its execution. For maximum performance, make sure that
 179 library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
 180
 181 If you are in the library/ folder of HTML Purifier, you can set the
 182 appropriate permissions using:
 183
 184     chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
 185
 186 If the above command doesn't work, you may need to assign write permissions
 187 to all. This may be necessary if your webserver runs as nobody, but is
 188 not recommended since it means any other user can write files in the
 189 directory. Use:
 190
 191     chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
 192
 193 You can also chmod files via your FTP client; this option
 194 is usually accessible by right clicking the corresponding directory and
 195 then selecting "chmod" or "file permissions".
 196
 197 Starting with 2.0.1, HTML Purifier will generate friendly error messages
 198 that will tell you exactly what you have to chmod the directory to, if in doubt,
 199 follow its advice.
 200
 201 If you are unable or unwilling to give write permissions to the cache
 202 directory, you can either disable the cache (and suffer a performance
 203 hit):
 204
 205     $config->set('Core', 'DefinitionCache', null);
 206
 207 Or move the cache directory somewhere else (no trailing slash):
 208
 209     $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
 210
 211
 212 ---------------------------------------------------------------------------
 213 6.   Using the code
 214
 215 The interface is mind-numbingly simple:
 216
 217     $purifier = new HTMLPurifier();
 218     $clean_html = $purifier->purify( $dirty_html );
 219
 220 ...or, if you're using the configuration object:
 221
 222     $purifier = new HTMLPurifier($config);
 223     $clean_html = $purifier->purify( $dirty_html );
 224
 225 That's it!  For more examples, check out docs/examples/ (they aren't very
 226 different though).  Also, docs/enduser-slow.html gives advice on what to
 227 do if HTML Purifier is slowing down your application.
 228
 229
 230 ---------------------------------------------------------------------------
 231 7.   Quick install
 232
 233 First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
 234 writable by the webserver (see Section 5: Caching above for details).
 235 If your website is in UTF-8 and XHTML Transitional, use this code:
 236
 237 <?php
 238     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 239
 240     $purifier = new HTMLPurifier();
 241     $clean_html = $purifier->purify($dirty_html);
 242 ?>
 243
 244 If your website is in a different encoding or doctype, use this code:
 245
 246 <?php
 247     require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
 248
 249     $config = HTMLPurifier_Config::createDefault();
 250     $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
 251     $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
 252     $purifier = new HTMLPurifier($config);
 253
 254     $clean_html = $purifier->purify($dirty_html);
 255 ?>
 256