HTMLPurifier Class Reference

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

Collaboration diagram for HTMLPurifier:

Public Member Functions
	__construct ($config=null)
	Initializes the purifier. More...
	addFilter ($filter)
	Adds a filter to process the output. More...
	purify ($html, $config=null)
	Filters an HTML snippet/document to be XSS-free and standards-compliant. More...
	purifyArray ($array_of_html, $config=null)
	Filters an array of HTML snippets. More...

Static Public Member Functions
static	instance ($prototype=null)
	Singleton for enforcing just one HTML Purifier in your system. More...
static	getInstance ($prototype=null)
	Singleton for enforcing just one HTML Purifier in your system. More...

Data Fields
	$version = '4.7.0'
	Version of HTML Purifier. More...
const	VERSION = '4.7.0'
	Constant with version of HTML Purifier. More...
	$config
	Global configuration object. More...
	$context
	Resultant context of last run purification. More...

Protected Attributes
	$strategy
	HTMLPurifier_Strategy_Core More...
	$generator
	HTMLPurifier_Generator More...

Private Attributes
	$filters = array()
	Array of extra filter objects to run on HTML, for backwards compatibility. More...

Static Private Attributes
static	$instance
	Single instance of HTML Purifier. More...

Detailed Description

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:

1. Instance: new HTMLPurifier($config)
2. 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.

Definition at line 54 of file HTMLPurifier.php.

Constructor & Destructor Documentation

__construct()

HTMLPurifier::__construct

(

$config = null

)

Initializes the purifier.

Parameters

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.

Definition at line 114 of file HTMLPurifier.php.

References $config, and HTMLPurifier_Config\create().

    {
        $this->config = HTMLPurifier_Config::create($config);
        $this->strategy = new HTMLPurifier_Strategy_Core();
    }

Here is the call graph for this function:

Member Function Documentation

addFilter()

HTMLPurifier::addFilter

(

$filter

)

Adds a filter to process the output.

First come first serve

Parameters

HTMLPurifier_Filter

$filter

HTMLPurifier_Filter object

Definition at line 125 of file HTMLPurifier.php.

    {
        trigger_error(
            'HTMLPurifier->addFilter() is deprecated, use configuration directives' .
            ' in the Filter namespace or Filter.Custom',
            E_USER_WARNING
        );
        $this->filters[] = $filter;
    }

getInstance()

static HTMLPurifier::getInstance (   $prototype = null )

static

Singleton for enforcing just one HTML Purifier in your system.

Parameters

HTMLPurifier | HTMLPurifier_Config

$prototype

Optional prototype HTMLPurifier instance to overload singleton with, or HTMLPurifier_Config instance to configure the generated version with.

Returns

HTMLPurifier

Note

Backwards compatibility, see instance()

Definition at line 286 of file HTMLPurifier.php.

References instance().

Referenced by HTMLPurifier_ConfigSchema_Builder_Xml\writeHTMLDiv().

    {
        return HTMLPurifier::instance($prototype);
    }

Here is the call graph for this function:

Here is the caller graph for this function:

instance()

static HTMLPurifier::instance (   $prototype = null )

static

Singleton for enforcing just one HTML Purifier in your system.

Parameters

HTMLPurifier | HTMLPurifier_Config

$prototype

Optional prototype HTMLPurifier instance to overload singleton with, or HTMLPurifier_Config instance to configure the generated version with.

Returns

HTMLPurifier

Definition at line 261 of file HTMLPurifier.php.

References HTMLPurifier().

Referenced by getInstance().

    {
        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;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

purify()

HTMLPurifier::purify	(		$html,
			$config = null
	)

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

Parameters

string	$html	String of HTML to purify
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.

Returns

string Purified HTML

Definition at line 146 of file HTMLPurifier.php.

References $config, $context, $filters, $html, HTMLPurifier_IDAccumulator\build(), HTMLPurifier_Encoder\convertFromUTF8(), HTMLPurifier_Encoder\convertToUTF8(), HTMLPurifier_Lexer\create(), HTMLPurifier_Config\create(), and HTMLPurifier_LanguageFactory\instance().

Referenced by purifyArray().

    {
        // :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;
    }

Here is the call graph for this function:

Here is the caller graph for this function:

purifyArray()

HTMLPurifier::purifyArray	(		$array_of_html,
			$config = null
	)

Filters an array of HTML snippets.

Parameters

	string[]	$array_of_html Array of html snippets
HTMLPurifier_Config	$config	Optional config object for this operation. See HTMLPurifier::purify() for more details.

Returns

string[] Array of purified HTML

Definition at line 240 of file HTMLPurifier.php.

References $config, $context, $html, and purify().

    {
        $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;
    }

Here is the call graph for this function:

Field Documentation

$config

HTMLPurifier::$config

Global configuration object.

HTMLPurifier_Config

Definition at line 72 of file HTMLPurifier.php.

Referenced by __construct(), purify(), and purifyArray().

$context

HTMLPurifier::$context

Resultant context of last run purification.

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

Definition at line 102 of file HTMLPurifier.php.

Referenced by purify(), and purifyArray().

$filters

HTMLPurifier::$filters = array()

private

Array of extra filter objects to run on HTML, for backwards compatibility.

HTMLPurifier_Filter[]

Definition at line 79 of file HTMLPurifier.php.

Referenced by purify().

$generator

HTMLPurifier::$generator

protected

HTMLPurifier_Generator

Definition at line 95 of file HTMLPurifier.php.

$instance

HTMLPurifier::$instance

staticprivate

Single instance of HTML Purifier.

HTMLPurifier

Definition at line 85 of file HTMLPurifier.php.

$strategy

HTMLPurifier::$strategy

protected

HTMLPurifier_Strategy_Core

Definition at line 90 of file HTMLPurifier.php.

$version

HTMLPurifier::$version = '4.7.0'

Version of HTML Purifier.

string

Definition at line 61 of file HTMLPurifier.php.

VERSION

const HTMLPurifier::VERSION = '4.7.0'

Constant with version of HTML Purifier.

Definition at line 66 of file HTMLPurifier.php.

---

The documentation for this class was generated from the following file:

• Services/Html/HtmlPurifier/library/HTMLPurifier.php