/tine20/library/HTMLPurifier/HTMLPurifier.php

<?php



/*! @mainpage

 *

 * HTML Purifier is an HTML filter that will take an arbitrary snippet of

 * HTML and rigorously test, validate and filter it into a version that

 * is safe for output onto webpages. It achieves this by:

 *

 *  -# Lexing (parsing into tokens) the document,

 *  -# Executing various strategies on the tokens:

 *      -# Removing all elements not in the whitelist,

 *      -# Making the tokens well-formed,

 *      -# Fixing the nesting of the nodes, and

 *      -# Validating attributes of the nodes; and

 *  -# Generating HTML from the purified tokens.

 *

 * However, most users will only need to interface with the HTMLPurifier

 * and HTMLPurifier_Config.

 */



/*

    HTML Purifier 4.6.0 - Standards Compliant HTML Filtering

    Copyright (C) 2006-2008 Edward Z. Yang



    This library is free software; you can redistribute it and/or

    modify it under the terms of the GNU Lesser General Public

    License as published by the Free Software Foundation; either

    version 2.1 of the License, or (at your option) any later version.



    This library is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    Lesser General Public License for more details.



    You should have received a copy of the GNU Lesser General Public

    License along with this library; if not, write to the Free Software

    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

 */



/**

 * Facade that coordinates HTML Purifier's subsystems in order to purify HTML.

 *

 * @note There are several points in which configuration can be specified

 *       for HTML Purifier.  The precedence of these (from lowest to

 *       highest) is as follows:

 *          -# Instance: new HTMLPurifier($config)

 *          -# Invocation: purify($html, $config)

 *       These configurations are entirely independent of each other and

 *       are *not* merged (this behavior may change in the future).

 *

 * @todo We need an easier way to inject strategies using the configuration

 *       object.

 */

class HTMLPurifier

{



    /**

     * Version of HTML Purifier.

     * @type string

     */

    public $version = '4.6.0';



    /**

     * Constant with version of HTML Purifier.

     */

    const VERSION = '4.6.0';



    /**

     * Global configuration object.

     * @type HTMLPurifier_Config

     */

    public $config;



    /**

     * Array of extra filter objects to run on HTML,

     * for backwards compatibility.

     * @type HTMLPurifier_Filter[]

     */

    private $filters = array();



    /**

     * Single instance of HTML Purifier.

     * @type HTMLPurifier

     */

    private static $instance;



    /**

     * @type HTMLPurifier_Strategy_Core

     */

    protected $strategy;



    /**

     * @type HTMLPurifier_Generator

     */

    protected $generator;



    /**

     * Resultant context of last run purification.

     * Is an array of contexts if the last called method was purifyArray().

     * @type HTMLPurifier_Context

     */

    public $context;



    /**

     * Initializes the purifier.

     *

     * @param HTMLPurifier_Config $config Optional HTMLPurifier_Config object

     *                for all instances of the purifier, if omitted, a default

     *                configuration is supplied (which can be overridden on a

     *                per-use basis).

     *                The parameter can also be any type that

     *                HTMLPurifier_Config::create() supports.

     */

    public function __construct($config = null)

    {

        $this->config = HTMLPurifier_Config::create($config);

        $this->strategy = new HTMLPurifier_Strategy_Core();

    }



    /**

     * Adds a filter to process the output. First come first serve

     *

     * @param HTMLPurifier_Filter $filter HTMLPurifier_Filter object

     */

    public function addFilter($filter)

    {

        trigger_error(

            'HTMLPurifier->addFilter() is deprecated, use configuration directives' .

            ' in the Filter namespace or Filter.Custom',

            E_USER_WARNING

        );

        $this->filters[] = $filter;

    }



    /**

     * Filters an HTML snippet/document to be XSS-free and standards-compliant.

     *

     * @param string $html String of HTML to purify

     * @param HTMLPurifier_Config $config Config object for this operation,

     *                if omitted, defaults to the config object specified during this

     *                object's construction. The parameter can also be any type

     *                that HTMLPurifier_Config::create() supports.

     *

     * @return string Purified HTML

     */

    public function purify($html, $config = null)

    {

        // :TODO: make the config merge in, instead of replace

        $config = $config ? HTMLPurifier_Config::create($config) : $this->config;



        // implementation is partially environment dependant, partially

        // configuration dependant

        $lexer = HTMLPurifier_Lexer::create($config);



        $context = new HTMLPurifier_Context();



        // setup HTML generator

        $this->generator = new HTMLPurifier_Generator($config, $context);

        $context->register('Generator', $this->generator);



        // set up global context variables

        if ($config->get('Core.CollectErrors')) {

            // may get moved out if other facilities use it

            $language_factory = HTMLPurifier_LanguageFactory::instance();

            $language = $language_factory->create($config, $context);

            $context->register('Locale', $language);



            $error_collector = new HTMLPurifier_ErrorCollector($context);

            $context->register('ErrorCollector', $error_collector);

        }



        // setup id_accumulator context, necessary due to the fact that

        // AttrValidator can be called from many places

        $id_accumulator = HTMLPurifier_IDAccumulator::build($config, $context);

        $context->register('IDAccumulator', $id_accumulator);



        $html = HTMLPurifier_Encoder::convertToUTF8($html, $config, $context);



        // setup filters

        $filter_flags = $config->getBatch('Filter');

        $custom_filters = $filter_flags['Custom'];

        unset($filter_flags['Custom']);

        $filters = array();

        foreach ($filter_flags as $filter => $flag) {

            if (!$flag) {

                continue;

            }

            if (strpos($filter, '.') !== false) {

                continue;

            }

            $class = "HTMLPurifier_Filter_$filter";

            $filters[] = new $class;

        }

        foreach ($custom_filters as $filter) {

            // maybe "HTMLPurifier_Filter_$filter", but be consistent with AutoFormat

            $filters[] = $filter;

        }

        $filters = array_merge($filters, $this->filters);

        // maybe prepare(), but later



        for ($i = 0, $filter_size = count($filters); $i < $filter_size; $i++) {

            $html = $filters[$i]->preFilter($html, $config, $context);

        }



        // purified HTML

        $html =

            $this->generator->generateFromTokens(

                // list of tokens

                $this->strategy->execute(

                    // list of un-purified tokens

                    $lexer->tokenizeHTML(

                        // un-purified HTML

                        $html,

                        $config,

                        $context

                    ),

                    $config,

                    $context

                )

            );



        for ($i = $filter_size - 1; $i >= 0; $i--) {

            $html = $filters[$i]->postFilter($html, $config, $context);

        }



        $html = HTMLPurifier_Encoder::convertFromUTF8($html, $config, $context);

        $this->context =& $context;

        return $html;

    }



    /**

     * Filters an array of HTML snippets

     *

     * @param string[] $array_of_html Array of html snippets

     * @param HTMLPurifier_Config $config Optional config object for this operation.

     *                See HTMLPurifier::purify() for more details.

     *

     * @return string[] Array of purified HTML

     */

    public function purifyArray($array_of_html, $config = null)

    {

        $context_array = array();

        foreach ($array_of_html as $key => $html) {

            $array_of_html[$key] = $this->purify($html, $config);

            $context_array[$key] = $this->context;

        }

        $this->context = $context_array;

        return $array_of_html;

    }



    /**

     * Singleton for enforcing just one HTML Purifier in your system

     *

     * @param HTMLPurifier|HTMLPurifier_Config $prototype Optional prototype

     *                   HTMLPurifier instance to overload singleton with,

     *                   or HTMLPurifier_Config instance to configure the

     *                   generated version with.

     *

     * @return HTMLPurifier

     */

    public static function instance($prototype = null)

    {

        if (!self::$instance || $prototype) {

            if ($prototype instanceof HTMLPurifier) {

                self::$instance = $prototype;

            } elseif ($prototype) {

                self::$instance = new HTMLPurifier($prototype);

            } else {

                self::$instance = new HTMLPurifier();

            }

        }

        return self::$instance;

    }



    /**

     * Singleton for enforcing just one HTML Purifier in your system

     *

     * @param HTMLPurifier|HTMLPurifier_Config $prototype Optional prototype

     *                   HTMLPurifier instance to overload singleton with,

     *                   or HTMLPurifier_Config instance to configure the

     *                   generated version with.

     *

     * @return HTMLPurifier

     * @note Backwards compatibility, see instance()

     */

    public static function getInstance($prototype = null)

    {

        return HTMLPurifier::instance($prototype);

    }

}



// vim: et sw=4 sts=4