aboutsummaryrefslogtreecommitdiffstats
path: root/lib/htmlpurifier/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'lib/htmlpurifier/INSTALL')
-rw-r--r--lib/htmlpurifier/INSTALL374
1 files changed, 0 insertions, 374 deletions
diff --git a/lib/htmlpurifier/INSTALL b/lib/htmlpurifier/INSTALL
deleted file mode 100644
index 677c04aa0..000000000
--- a/lib/htmlpurifier/INSTALL
+++ /dev/null
@@ -1,374 +0,0 @@
-
-Install
- How to install HTML Purifier
-
-HTML Purifier is designed to run out of the box, so actually using the
-library is extremely easy. (Although... if you were looking for a
-step-by-step installation GUI, you've downloaded the wrong software!)
-
-While the impatient can get going immediately with some of the sample
-code at the bottom of this library, it's well worth reading this entire
-document--most of the other documentation assumes that you are familiar
-with these contents.
-
-
----------------------------------------------------------------------------
-1. Compatibility
-
-HTML Purifier is PHP 5 only, and is actively tested from PHP 5.0.5 and
-up. It has no core dependencies with other libraries. PHP
-4 support was deprecated on December 31, 2007 with HTML Purifier 3.0.0.
-HTML Purifier is not compatible with zend.ze1_compatibility_mode.
-
-These optional extensions can enhance the capabilities of HTML Purifier:
-
- * iconv : Converts text to and from non-UTF-8 encodings
- * bcmath : Used for unit conversion and imagecrash protection
- * tidy : Used for pretty-printing HTML
-
-These optional libraries can enhance the capabilities of HTML Purifier:
-
- * CSSTidy : Clean CSS stylesheets using %Core.ExtractStyleBlocks
- * Net_IDNA2 (PEAR) : IRI support using %Core.EnableIDNA
-
----------------------------------------------------------------------------
-2. Reconnaissance
-
-A big plus of HTML Purifier is its inerrant support of standards, so
-your web-pages should be standards-compliant. (They should also use
-semantic markup, but that's another issue altogether, one HTML Purifier
-cannot fix without reading your mind.)
-
-HTML Purifier can process these doctypes:
-
-* XHTML 1.0 Transitional (default)
-* XHTML 1.0 Strict
-* HTML 4.01 Transitional
-* HTML 4.01 Strict
-* XHTML 1.1
-
-...and these character encodings:
-
-* UTF-8 (default)
-* Any encoding iconv supports (with crippled internationalization support)
-
-These defaults reflect what my choices would be if I were authoring an
-HTML document, however, what you choose depends on the nature of your
-codebase. If you don't know what doctype you are using, you can determine
-the doctype from this identifier at the top of your source code:
-
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-...and the character encoding from this code:
-
- <meta http-equiv="Content-type" content="text/html;charset=ENCODING">
-
-If the character encoding declaration is missing, STOP NOW, and
-read 'docs/enduser-utf8.html' (web accessible at
-http://htmlpurifier.org/docs/enduser-utf8.html). In fact, even if it is
-present, read this document anyway, as many websites specify their
-document's character encoding incorrectly.
-
-
----------------------------------------------------------------------------
-3. Including the library
-
-The procedure is quite simple:
-
- require_once '/path/to/library/HTMLPurifier.auto.php';
-
-This will setup an autoloader, so the library's files are only included
-when you use them.
-
-Only the contents in the library/ folder are necessary, so you can remove
-everything else when using HTML Purifier in a production environment.
-
-If you installed HTML Purifier via PEAR, all you need to do is:
-
- require_once 'HTMLPurifier.auto.php';
-
-Please note that the usual PEAR practice of including just the classes you
-want will not work with HTML Purifier's autoloading scheme.
-
-Advanced users, read on; other users can skip to section 4.
-
-Autoload compatibility
-----------------------
-
- HTML Purifier attempts to be as smart as possible when registering an
- autoloader, but there are some cases where you will need to change
- your own code to accomodate HTML Purifier. These are those cases:
-
- PHP VERSION IS LESS THAN 5.1.2, AND YOU'VE DEFINED __autoload
- Because spl_autoload_register() doesn't exist in early versions
- of PHP 5, HTML Purifier has no way of adding itself to the autoload
- stack. Modify your __autoload function to test
- HTMLPurifier_Bootstrap::autoload($class)
-
- For example, suppose your autoload function looks like this:
-
- function __autoload($class) {
- require str_replace('_', '/', $class) . '.php';
- return true;
- }
-
- A modified version with HTML Purifier would look like this:
-
- function __autoload($class) {
- if (HTMLPurifier_Bootstrap::autoload($class)) return true;
- require str_replace('_', '/', $class) . '.php';
- return true;
- }
-
- Note that there *is* some custom behavior in our autoloader; the
- original autoloader in our example would work for 99% of the time,
- but would fail when including language files.
-
- AN __autoload FUNCTION IS DECLARED AFTER OUR AUTOLOADER IS REGISTERED
- spl_autoload_register() has the curious behavior of disabling
- the existing __autoload() handler. Users need to explicitly
- spl_autoload_register('__autoload'). Because we use SPL when it
- is available, __autoload() will ALWAYS be disabled. If __autoload()
- is declared before HTML Purifier is loaded, this is not a problem:
- HTML Purifier will register the function for you. But if it is
- declared afterwards, it will mysteriously not work. This
- snippet of code (after your autoloader is defined) will fix it:
-
- spl_autoload_register('__autoload')
-
- Users should also be on guard if they use a version of PHP previous
- to 5.1.2 without an autoloader--HTML Purifier will define __autoload()
- for you, which can collide with an autoloader that was added by *you*
- later.
-
-
-For better performance
-----------------------
-
- Opcode caches, which greatly speed up PHP initialization for scripts
- with large amounts of code (HTML Purifier included), don't like
- autoloaders. We offer an include file that includes all of HTML Purifier's
- files in one go in an opcode cache friendly manner:
-
- // If /path/to/library isn't already in your include path, uncomment
- // the below line:
- // require '/path/to/library/HTMLPurifier.path.php';
-
- require 'HTMLPurifier.includes.php';
-
- Optional components still need to be included--you'll know if you try to
- use a feature and you get a class doesn't exists error! The autoloader
- can be used in conjunction with this approach to catch classes that are
- missing. Simply add this afterwards:
-
- require 'HTMLPurifier.autoload.php';
-
-Standalone version
-------------------
-
- HTML Purifier has a standalone distribution; you can also generate
- a standalone file from the full version by running the script
- maintenance/generate-standalone.php . The standalone version has the
- benefit of having most of its code in one file, so parsing is much
- faster and the library is easier to manage.
-
- If HTMLPurifier.standalone.php exists in the library directory, you
- can use it like this:
-
- require '/path/to/HTMLPurifier.standalone.php';
-
- This is equivalent to including HTMLPurifier.includes.php, except that
- the contents of standalone/ will be added to your path. To override this
- behavior, specify a new HTMLPURIFIER_PREFIX where standalone files can
- be found (usually, this will be one directory up, the "true" library
- directory in full distributions). Don't forget to set your path too!
-
- The autoloader can be added to the end to ensure the classes are
- loaded when necessary; otherwise you can manually include them.
- To use the autoloader, use this:
-
- require 'HTMLPurifier.autoload.php';
-
-For advanced users
-------------------
-
- HTMLPurifier.auto.php performs a number of operations that can be done
- individually. These are:
-
- HTMLPurifier.path.php
- Puts /path/to/library in the include path. For high performance,
- this should be done in php.ini.
-
- HTMLPurifier.autoload.php
- Registers our autoload handler HTMLPurifier_Bootstrap::autoload($class).
-
- You can do these operations by yourself--in fact, you must modify your own
- autoload handler if you are using a version of PHP earlier than PHP 5.1.2
- (See "Autoload compatibility" above).
-
-
----------------------------------------------------------------------------
-4. Configuration
-
-HTML Purifier is designed to run out-of-the-box, but occasionally HTML
-Purifier needs to be told what to do. If you answer no to any of these
-questions, read on; otherwise, you can skip to the next section (or, if you're
-into configuring things just for the heck of it, skip to 4.3).
-
-* Am I using UTF-8?
-* Am I using XHTML 1.0 Transitional?
-
-If you answered no to any of these questions, instantiate a configuration
-object and read on:
-
- $config = HTMLPurifier_Config::createDefault();
-
-
-4.1. Setting a different character encoding
-
-You really shouldn't use any other encoding except UTF-8, especially if you
-plan to support multilingual websites (read section three for more details).
-However, switching to UTF-8 is not always immediately feasible, so we can
-adapt.
-
-HTML Purifier uses iconv to support other character encodings, as such,
-any encoding that iconv supports <http://www.gnu.org/software/libiconv/>
-HTML Purifier supports with this code:
-
- $config->set('Core.Encoding', /* put your encoding here */);
-
-An example usage for Latin-1 websites (the most common encoding for English
-websites):
-
- $config->set('Core.Encoding', 'ISO-8859-1');
-
-Note that HTML Purifier's support for non-Unicode encodings is crippled by the
-fact that any character not supported by that encoding will be silently
-dropped, EVEN if it is ampersand escaped. If you want to work around
-this, you are welcome to read docs/enduser-utf8.html for a fix,
-but please be cognizant of the issues the "solution" creates (for this
-reason, I do not include the solution in this document).
-
-
-4.2. Setting a different doctype
-
-For those of you using HTML 4.01 Transitional, you can disable
-XHTML output like this:
-
- $config->set('HTML.Doctype', 'HTML 4.01 Transitional');
-
-Other supported doctypes include:
-
- * HTML 4.01 Strict
- * HTML 4.01 Transitional
- * XHTML 1.0 Strict
- * XHTML 1.0 Transitional
- * XHTML 1.1
-
-
-4.3. Other settings
-
-There are more configuration directives which can be read about
-here: <http://htmlpurifier.org/live/configdoc/plain.html> They're a bit boring,
-but they can help out for those of you who like to exert maximum control over
-your code. Some of the more interesting ones are configurable at the
-demo <http://htmlpurifier.org/demo.php> and are well worth looking into
-for your own system.
-
-For example, you can fine tune allowed elements and attributes, convert
-relative URLs to absolute ones, and even autoparagraph input text! These
-are, respectively, %HTML.Allowed, %URI.MakeAbsolute and %URI.Base, and
-%AutoFormat.AutoParagraph. The %Namespace.Directive naming convention
-translates to:
-
- $config->set('Namespace.Directive', $value);
-
-E.g.
-
- $config->set('HTML.Allowed', 'p,b,a[href],i');
- $config->set('URI.Base', 'http://www.example.com');
- $config->set('URI.MakeAbsolute', true);
- $config->set('AutoFormat.AutoParagraph', true);
-
-
----------------------------------------------------------------------------
-5. Caching
-
-HTML Purifier generates some cache files (generally one or two) to speed up
-its execution. For maximum performance, make sure that
-library/HTMLPurifier/DefinitionCache/Serializer is writeable by the webserver.
-
-If you are in the library/ folder of HTML Purifier, you can set the
-appropriate permissions using:
-
- chmod -R 0755 HTMLPurifier/DefinitionCache/Serializer
-
-If the above command doesn't work, you may need to assign write permissions
-to all. This may be necessary if your webserver runs as nobody, but is
-not recommended since it means any other user can write files in the
-directory. Use:
-
- chmod -R 0777 HTMLPurifier/DefinitionCache/Serializer
-
-You can also chmod files via your FTP client; this option
-is usually accessible by right clicking the corresponding directory and
-then selecting "chmod" or "file permissions".
-
-Starting with 2.0.1, HTML Purifier will generate friendly error messages
-that will tell you exactly what you have to chmod the directory to, if in doubt,
-follow its advice.
-
-If you are unable or unwilling to give write permissions to the cache
-directory, you can either disable the cache (and suffer a performance
-hit):
-
- $config->set('Core.DefinitionCache', null);
-
-Or move the cache directory somewhere else (no trailing slash):
-
- $config->set('Cache.SerializerPath', '/home/user/absolute/path');
-
-
----------------------------------------------------------------------------
-6. Using the code
-
-The interface is mind-numbingly simple:
-
- $purifier = new HTMLPurifier($config);
- $clean_html = $purifier->purify( $dirty_html );
-
-That's it! For more examples, check out docs/examples/ (they aren't very
-different though). Also, docs/enduser-slow.html gives advice on what to
-do if HTML Purifier is slowing down your application.
-
-
----------------------------------------------------------------------------
-7. Quick install
-
-First, make sure library/HTMLPurifier/DefinitionCache/Serializer is
-writable by the webserver (see Section 5: Caching above for details).
-If your website is in UTF-8 and XHTML Transitional, use this code:
-
-<?php
- require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
-
- $config = HTMLPurifier_Config::createDefault();
- $purifier = new HTMLPurifier($config);
- $clean_html = $purifier->purify($dirty_html);
-?>
-
-If your website is in a different encoding or doctype, use this code:
-
-<?php
- require_once '/path/to/htmlpurifier/library/HTMLPurifier.auto.php';
-
- $config = HTMLPurifier_Config::createDefault();
- $config->set('Core.Encoding', 'ISO-8859-1'); // replace with your encoding
- $config->set('HTML.Doctype', 'HTML 4.01 Transitional'); // replace with your doctype
- $purifier = new HTMLPurifier($config);
-
- $clean_html = $purifier->purify($dirty_html);
-?>
-
- vim: et sw=4 sts=4