INSTALL 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373
  1. Install
  2. How to install HTML Purifier
  3. HTML Purifier is designed to run out of the box, so actually using the
  4. library is extremely easy. (Although... if you were looking for a
  5. step-by-step installation GUI, you've downloaded the wrong software!)
  6. While the impatient can get going immediately with some of the sample
  7. code at the bottom of this library, it's well worth reading this entire
  8. document--most of the other documentation assumes that you are familiar
  9. with these contents.
  10. ---------------------------------------------------------------------------
  11. 1. Compatibility
  12. HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.5 and
  13. up. It has no core dependencies with other libraries. PHP
  14. 4 support was deprecated on December 31, 2007 with HTML Purifier 3.0.0.
  15. These optional extensions can enhance the capabilities of HTML Purifier:
  16. * iconv : Converts text to and from non-UTF-8 encodings
  17. * bcmath : Used for unit conversion and imagecrash protection
  18. * tidy : Used for pretty-printing HTML
  19. ---------------------------------------------------------------------------
  20. 2. Reconnaissance
  21. A big plus of HTML Purifier is its inerrant support of standards, so
  22. your web-pages should be standards-compliant. (They should also use
  23. semantic markup, but that's another issue altogether, one HTML Purifier
  24. cannot fix without reading your mind.)
  25. HTML Purifier can process these doctypes:
  26. * XHTML 1.0 Transitional (default)
  27. * XHTML 1.0 Strict
  28. * HTML 4.01 Transitional
  29. * HTML 4.01 Strict
  30. * XHTML 1.1
  31. ...and these character encodings:
  32. * UTF-8 (default)
  33. * Any encoding iconv supports (with crippled internationalization support)
  34. These defaults reflect what my choices would be if I were authoring an
  35. HTML document, however, what you choose depends on the nature of your
  36. codebase. If you don't know what doctype you are using, you can determine
  37. the doctype from this identifier at the top of your source code:
  38. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  39. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  40. ...and the character encoding from this code:
  41. <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
  42. If the character encoding declaration is missing, STOP NOW, and
  43. read 'docs/enduser-utf8.html' (web accessible at
  44. http://htmlpurifier.org/docs/enduser-utf8.html). In fact, even if it is
  45. present, read this document anyway, as many websites specify their
  46. document's character encoding incorrectly.
  47. ---------------------------------------------------------------------------
  48. 3. Including the library
  49. The procedure is quite simple:
  50. require_once '/path/to/library/HTMLPurifier.auto.php';
  51. This will setup an autoloader, so the library's files are only included
  52. when you use them.
  53. Only the contents in the library/ folder are necessary, so you can remove
  54. everything else when using HTML Purifier in a production environment.
  55. If you installed HTML Purifier via PEAR, all you need to do is:
  56. require_once 'HTMLPurifier.auto.php';
  57. Please note that the usual PEAR practice of including just the classes you
  58. want will not work with HTML Purifier's autoloading scheme.
  59. Advanced users, read on; other users can skip to section 4.
  60. Autoload compatibility
  61. ----------------------
  62. HTML Purifier attempts to be as smart as possible when registering an
  63. autoloader, but there are some cases where you will need to change
  64. your own code to accomodate HTML Purifier. These are those cases:
  65. PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
  66. Because spl_autoload_register() doesn't exist in early versions
  67. of PHP 5, HTML Purifier has no way of adding itself to the autoload
  68. stack. Modify your __autoload function to test
  69. HTMLPurifier_Bootstrap::autoload($class)
  70. For example, suppose your autoload function looks like this:
  71. function __autoload($class) {
  72. require str_replace('_', '/', $class) . '.php';
  73. return true;
  74. }
  75. A modified version with HTML Purifier would look like this:
  76. function __autoload($class) {
  77. if (HTMLPurifier_Bootstrap::autoload($class)) return true;
  78. require str_replace('_', '/', $class) . '.php';
  79. return true;
  80. }
  81. Note that there *is* some custom behavior in our autoloader; the
  82. original autoloader in our example would work for 99% of the time,
  83. but would fail when including language files.
  84. AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
  85. spl_autoload_register() has the curious behavior of disabling
  86. the existing __autoload() handler. Users need to explicitly
  87. spl_autoload_register('__autoload'). Because we use SPL when it
  88. is available, __autoload() will ALWAYS be disabled. If __autoload()
  89. is declared before HTML Purifier is loaded, this is not a problem:
  90. HTML Purifier will register the function for you. But if it is
  91. declared afterwards, it will mysteriously not work. This
  92. snippet of code (after your autoloader is defined) will fix it:
  93. spl_autoload_register('__autoload')
  94. Users should also be on guard if they use a version of PHP previous
  95. to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
  96. for you, which can collide with an autoloader that was added by *you*
  97. later.
  98. For better performance
  99. ----------------------
  100. Opcode caches, which greatly speed up PHP initialization for scripts
  101. with large amounts of code (HTML Purifier included), don't like
  102. autoloaders. We offer an include file that includes all of HTML Purifier's
  103. files in one go in an opcode cache friendly manner:
  104. // If /path/to/library isn't already in your include path, uncomment
  105. // the below line:
  106. // require '/path/to/library/HTMLPurifier.path.php';
  107. require 'HTMLPurifier.includes.php';
  108. Optional components still need to be included--you'll know if you try to
  109. use a feature and you get a class doesn't exists error! The autoloader
  110. can be used in conjunction with this approach to catch classes that are
  111. missing. Simply add this afterwards:
  112. require 'HTMLPurifier.autoload.php';
  113. Standalone version
  114. ------------------
  115. HTML Purifier has a standalone distribution; you can also generate
  116. a standalone file from the full version by running the script
  117. maintenance/generate-standalone.php . The standalone version has the
  118. benefit of having most of its code in one file, so parsing is much
  119. faster and the library is easier to manage.
  120. If HTMLPurifier.standalone.php exists in the library directory, you
  121. can use it like this:
  122. require '/path/to/HTMLPurifier.standalone.php';
  123. This is equivalent to including HTMLPurifier.includes.php, except that
  124. the contents of standalone/ will be added to your path. To override this
  125. behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
  126. be found (usually, this will be one directory up, the "true" library
  127. directory in full distributions). Don't forget to set your path too!
  128. The autoloader can be added to the end to ensure the classes are
  129. loaded when necessary; otherwise you can manually include them.
  130. To use the autoloader, use this:
  131. require 'HTMLPurifier.autoload.php';
  132. For advanced users
  133. ------------------
  134. HTMLPurifier.auto.php performs a number of operations that can be done
  135. individually. These are:
  136. HTMLPurifier.path.php
  137. Puts /path/to/library in the include path. For high performance,
  138. this should be done in php.ini.
  139. HTMLPurifier.autoload.php
  140. Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
  141. You can do these operations by yourself--in fact, you must modify your own
  142. autoload handler if you are using a version of PHP earlier than PHP 5.1.2
  143. (See "Autoload compatibility" above).
  144. ---------------------------------------------------------------------------
  145. 4. Configuration
  146. HTML Purifier is designed to run out-of-the-box, but occasionally HTML
  147. Purifier needs to be told what to do. If you answer no to any of these
  148. questions, read on; otherwise, you can skip to the next section (or, if you're
  149. into configuring things just for the heck of it, skip to 4.3).
  150. * Am I using UTF-8?
  151. * Am I using XHTML 1.0 Transitional?
  152. If you answered no to any of these questions, instantiate a configuration
  153. object and read on:
  154. $config = HTMLPurifier_Config::createDefault();
  155. 4.1. Setting a different character encoding
  156. You really shouldn't use any other encoding except UTF-8, especially if you
  157. plan to support multilingual websites (read section three for more details).
  158. However, switching to UTF-8 is not always immediately feasible, so we can
  159. adapt.
  160. HTML Purifier uses iconv to support other character encodings, as such,
  161. any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
  162. HTML Purifier supports with this code:
  163. $config->set('Core', 'Encoding', /* put your encoding here */);
  164. An example usage for Latin-1 websites (the most common encoding for English
  165. websites):
  166. $config->set('Core', 'Encoding', 'ISO-8859-1');
  167. Note that HTML Purifier's support for non-Unicode encodings is crippled by the
  168. fact that any character not supported by that encoding will be silently
  169. dropped, EVEN if it is ampersand escaped. If you want to work around
  170. this, you are welcome to read docs/enduser-utf8.html for a fix,
  171. but please be cognizant of the issues the "solution" creates (for this
  172. reason, I do not include the solution in this document).
  173. 4.2. Setting a different doctype
  174. For those of you using HTML 4.01 Transitional, you can disable
  175. XHTML output like this:
  176. $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional');
  177. Other supported doctypes include:
  178. * HTML 4.01 Strict
  179. * HTML 4.01 Transitional
  180. * XHTML 1.0 Strict
  181. * XHTML 1.0 Transitional
  182. * XHTML 1.1
  183. 4.3. Other settings
  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. For example, you can fine tune allowed elements and attributes, convert
  191. relative URLs to absolute ones, and even autoparagraph input text! These
  192. are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
  193. %AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
  194. translates to:
  195. $config->set('Namespace', 'Directive', $value);
  196. E.g.
  197. $config->set('HTML', 'Allowed', 'p,b,a[href],i');
  198. $config->set('URI', 'Base', 'http://www.example.com');
  199. $config->set('URI', 'MakeAbsolute', true);
  200. $config->set('AutoFormat', 'AutoParagraph', true);
  201. ---------------------------------------------------------------------------
  202. 5. Caching
  203. HTML Purifier generates some cache files (generally one or two) to speed up
  204. its execution. For maximum performance, make sure that
  205. library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
  206. If you are in the library/ folder of HTML Purifier, you can set the
  207. appropriate permissions using:
  208. chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
  209. If the above command doesn't work, you may need to assign write permissions
  210. to all. This may be necessary if your webserver runs as nobody, but is
  211. not recommended since it means any other user can write files in the
  212. directory. Use:
  213. chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
  214. You can also chmod files via your FTP client; this option
  215. is usually accessible by right clicking the corresponding directory and
  216. then selecting "chmod" or "file permissions".
  217. Starting with 2.0.1, HTML Purifier will generate friendly error messages
  218. that will tell you exactly what you have to chmod the directory to, if in doubt,
  219. follow its advice.
  220. If you are unable or unwilling to give write permissions to the cache
  221. directory, you can either disable the cache (and suffer a performance
  222. hit):
  223. $config->set('Core', 'DefinitionCache', null);
  224. Or move the cache directory somewhere else (no trailing slash):
  225. $config->set('Cache', 'SerializerPath', '/home/user/absolute/path');
  226. ---------------------------------------------------------------------------
  227. 6. Using the code
  228. The interface is mind-numbingly simple:
  229. $purifier = new HTMLPurifier();
  230. $clean_html = $purifier->purify( $dirty_html );
  231. ...or, if you're using the configuration object:
  232. $purifier = new HTMLPurifier($config);
  233. $clean_html = $purifier->purify( $dirty_html );
  234. That's it! For more examples, check out docs/examples/ (they aren't very
  235. different though). Also, docs/enduser-slow.html gives advice on what to
  236. do if HTML Purifier is slowing down your application.
  237. ---------------------------------------------------------------------------
  238. 7. Quick install
  239. First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
  240. writable by the webserver (see Section 5: Caching above for details).
  241. If your website is in UTF-8 and XHTML Transitional, use this code:
  242. <?php
  243. require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
  244. $purifier = new HTMLPurifier();
  245. $clean_html = $purifier->purify($dirty_html);
  246. ?>
  247. If your website is in a different encoding or doctype, use this code:
  248. <?php
  249. require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
  250. $config = HTMLPurifier_Config::createDefault();
  251. $config->set('Core', 'Encoding', 'ISO-8859-1'); // replace with your encoding
  252. $config->set('HTML', 'Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
  253. $purifier = new HTMLPurifier($config);
  254. $clean_html = $purifier->purify($dirty_html);
  255. ?>
  256. vim: et sw=4 sts=4