mirror of
https://github.com/ezyang/htmlpurifier.git
synced 2024-09-19 18:55:19 +00:00
4f8d83506d
- Shuffle around TODO items, we're going to handle the URI deficiencies first - Fix bugs in documentation :-P git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@441 48356398-32a2-884e-a903-53898d9a118a
148 lines
4.8 KiB
Plaintext
148 lines
4.8 KiB
Plaintext
|
|
Install
|
|
How to install HTML Purifier
|
|
|
|
Being a library, there's no fancy GUI that will take you step-by-step through
|
|
configuring database credentials and other mumbo-jumbo. HTML Purifier is
|
|
designed to run "out of the box." Regardless, there are still a couple of
|
|
things you should be mindful of.
|
|
|
|
|
|
|
|
0. Compatibility
|
|
|
|
HTML Purifier works in both PHP 4 and PHP 5. I have run the test suite on
|
|
these versions:
|
|
|
|
- 4.3.9, 4.3.11
|
|
- 4.4.0, 4.4.4
|
|
- 5.0.0, 5.0.4
|
|
- 5.1.0, 5.1.6
|
|
|
|
And can confidently say that HTML Purifier should work in all versions
|
|
between and afterwards. HTML Purifier definitely does not support PHP 4.2,
|
|
and PHP 4.3 branch support may go further back than that, but I haven't tested
|
|
any earlier versions.
|
|
|
|
I have been unable to get PHP 5.0.5 working on my computer, so if someone
|
|
wants to test that, be my guest. All tests were done on Windows XP Home,
|
|
but operating system should not be a major factor in the library.
|
|
|
|
|
|
|
|
1. Including the proper files
|
|
|
|
The library/ directory must be added to your path: HTML Purifier will not be
|
|
able to find the necessary includes otherwise. This is as simple as:
|
|
|
|
set_include_path('/path/to/htmlpurifier/library' . PATH_SEPARATOR .
|
|
get_include_path() );
|
|
|
|
...replacing /path/to/htmlpurifier with the actual location of the folder. Don't
|
|
worry, HTML Purifier is namespaced so unless you have another file named
|
|
HTMLPurifier.php, the files won't collide with any of your includes.
|
|
|
|
Then, it's a simple matter of including the base file:
|
|
|
|
require_once 'HTMLPurifier.php';
|
|
|
|
...and you're good to go.
|
|
|
|
|
|
|
|
2. Preparing the proper environment
|
|
|
|
While no configuration is necessary, you first should take precautions regarding
|
|
the other output HTML that the filtered content will be going along with. Here
|
|
is a (short) checklist:
|
|
|
|
* Have I specified XHTML 1.0 Transitional as the doctype?
|
|
* Have I specified UTF-8 as the character encoding?
|
|
|
|
To find out what these are, browse to your website and view its source code.
|
|
You can figure out the doctype from the a declaration that looks like
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
or no doctype. You can figure out the character encoding by looking for
|
|
<meta http-equiv="Content-type" content="text/html;charset=ENCODING">
|
|
|
|
I cannot stress the importance of these two bullets enough. Omitting either
|
|
of them could have dire consequences not only for security but for plain
|
|
old usability. You can find a more in-depth discussion of why this is needed
|
|
in docs/security.txt, in the meantime, try to change your output so this is
|
|
the case. If you can't, well, we might be able to accomodate you (read
|
|
section 3).
|
|
|
|
|
|
|
|
3. Configuring HTML Purifier
|
|
|
|
HTML Purifier is designed to run out-of-the-box, but occasionally HTML
|
|
Purifier needs to be told what to do.
|
|
|
|
If, for some reason, you are unable to switch to UTF-8 immediately, you can
|
|
switch HTML Purifier's encoding. Note that the availability of encodings is
|
|
dependent on iconv, and you'll be missing characters if the charset you
|
|
choose doesn't have them.
|
|
|
|
$config->set('Core', 'Encoding', /* put your encoding here */);
|
|
|
|
An example usage for Latin-1 websites:
|
|
|
|
$config->set('Core', 'Encoding', 'ISO-8859-1');
|
|
|
|
For those of you stuck using HTML 4.01 Transitional, you can disable
|
|
XHTML output like this:
|
|
|
|
$config->set('Core', 'XHTML', false);
|
|
|
|
However, I strongly recommend that you use XHTML. Currently, we can only
|
|
guarantee transitional-complaint output, future versions will also allow strict
|
|
output.
|
|
|
|
|
|
|
|
3. Using the code
|
|
|
|
The interface is mind-numbingly simple:
|
|
|
|
$purifier = new HTMLPurifier();
|
|
$clean_html = $purifier->purify($dirty_html);
|
|
|
|
Or, if you're using the configuration object:
|
|
|
|
$purifier = new HTMLPurifier($config);
|
|
$clean_html = $purifier->purify($dirty_html);
|
|
|
|
That's it. For more examples, check out docs/examples/. Also, SLOW gives
|
|
advice on what to do if HTML Purifier is slowing down your application.
|
|
|
|
|
|
|
|
4. Quick install
|
|
|
|
If your website is in UTF-8 and XHTML Transitional, use this code:
|
|
|
|
<?php
|
|
set_include_path('/path/to/htmlpurifier/library'
|
|
. PATH_SEPARATOR . get_include_path() );
|
|
require_once 'HTMLPurifier.php';
|
|
$purifier = new HTMLPurifier();
|
|
|
|
$clean_html = $purifier->purify($dirty_html);
|
|
?>
|
|
|
|
If your website is in a different encoding or doctype, use this code:
|
|
|
|
<?php
|
|
set_include_path('/path/to/htmlpurifier/library'
|
|
. PATH_SEPARATOR . get_include_path() );
|
|
require_once 'HTMLPurifier.php';
|
|
|
|
$config = HTMLPurifier_Config::createDefault();
|
|
$config->set('Core', 'Encoding', 'ISO-8859-1'); //replace with your encoding
|
|
$config->set('Core', 'XHTML', true); //replace with false if HTML 4.01
|
|
$purifier = new HTMLPurifier($config);
|
|
|
|
$clean_html = $purifier->purify($dirty_html);
|
|
?> |