INSTALL

   1
   2 Install
   3     How to install HTMLPurifier
   4
   5 Being a library, there's no fancy GUI that will take you step-by-step through
   6 configuring database credentials and other mumbo-jumbo.  HTMLPurifier is
   7 designed to run "out of the box."  Regardless, there are still a couple of
   8 things you should be mindful of.
   9
  10
  11
  12 1.  Including the proper files
  13
  14 The library/ directory must be added to your path: HTMLPurifier will not be
  15 able to find the necessary includes otherwise.  This is as simple as:
  16
  17 set_include_path('/path/to/htmlpurifier/library' . PATH_SEPARATOR . get_include_path());
  18
  19 ...replacing /path/to/htmlpurifier with the actual location of the folder. Don't
  20 worry, HTMLPurifier is namespaced so unless you have another file named
  21 HTMLPurifier.php, the files won't collide with any of your includes.
  22
  23 Then, it's a simple matter of including the base file:
  24
  25 require_once 'HTMLPurifier.php';
  26
  27 ...and you're good to go.
  28
  29
  30
  31 2.  Preparing the proper environment
  32
  33 While no configuration is necessary, you first should take precautions regarding
  34 the other output HTML that the filtered content will be going along with.  Here
  35 is a (short) checklist:
  36
  37  * Have I specified XHTML 1.0 Transitional as the doctype?
  38  * Have I specified UTF-8 as the character encoding?
  39
  40 I cannot stress the importance of these two bullets enough.  Omitting either
  41 of them could have dire consequences not only for security but for plain
  42 old usability.  You can find a more in-depth discussion of why this is needed
  43 in docs/security.txt, in the meantime, try to change your output so this is
  44 the case.
  45
  46 If, for some reason, you are unable to switch to UTF-8 immediately, you can
  47 use iconv to convert the output of HTMLPurifier to your desired encoding.
  48 We may integrate support for other encodings in later releases, but for now,
  49 UTF-8 is all you should need.  (If you're not using UTF-8, switch now!)
  50
  51
  52
  53 3.   Using the code
  54
  55 The interface is mind-numbingly simple.
  56
  57 $purifier = new HTMLPurifier();
  58 $clean_html = $purifier->purify($dirty_html);
  59
  60 That's it.  For more examples, check out docs/examples/.  Also, SLOW gives
  61 advice on what to do if HTMLPurifier is slowing down your application.