mirrors/htmlpurifier
0
0
Fork 0
mirror of https://github.com/ezyang/htmlpurifier.git synced 2025-01-20 12:31:53 +00:00
Code Releases Activity

A bunch of PHPdoc and php codesniffer corrections - no functional code changes

Browse Source
This commit is contained in:
Synchro 2013-07-16 14:20:01 +02:00 committed by Edward Z. Yang
parent 75bd7abcc7
commit 29a3c70370
4 changed files with 394 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
library/HTMLPurifier.php
View File

@ -54,34 +54,47 @@
class HTMLPurifier class HTMLPurifier
{ {
/** Version of HTML Purifier */ /**
* @var string Version of HTML Purifier
*/
public $version = '4.5.0'; public $version = '4.5.0';
/** Constant with version of HTML Purifier */ /**
* Constant with version of HTML Purifier
*/
const VERSION = '4.5.0'; const VERSION = '4.5.0';
/** Global configuration object */ /**
* @var HTMLPurifier_Config Global configuration object
*/
public $config; public $config;
/** Array of extra HTMLPurifier_Filter objects to run on HTML, for backwards compatibility */ /**
* @var HTMLPurifier_Filter[] Array of extra filter objects to run on HTML,
* for backwards compatibility
*/
private $filters = array(); private $filters = array();
/** Single instance of HTML Purifier */ /**
* @var HTMLPurifier Single instance of HTML Purifier
*/
private static $instance; private static $instance;
protected $strategy, $generator; protected $strategy, $generator;
/** /**
* Resultant HTMLPurifier_Context of last run purification. Is an array * @var HTMLPurifier_Context Resultant context of last run purification.
* of contexts if the last called method was purifyArray(). * Is an array of contexts if the last called method was purifyArray().
*/ */
public $context; public $context;
/** /**
* Initializes the purifier. * Initializes the purifier.
* @param $config Optional HTMLPurifier_Config object for all instances of *
* the purifier, if omitted, a default configuration is * @param HTMLPurifier_Config $config Optional HTMLPurifier_Config object
* supplied (which can be overridden on a per-use basis). * 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 * The parameter can also be any type that
* HTMLPurifier_Config::create() supports. * HTMLPurifier_Config::create() supports.
*/ */
@ -95,22 +108,28 @@ class HTMLPurifier
/** /**
* Adds a filter to process the output. First come first serve * Adds a filter to process the output. First come first serve
* @param $filter HTMLPurifier_Filter object *
* @param HTMLPurifier_Filter $filter HTMLPurifier_Filter object
*/ */
public function addFilter($filter) { public function addFilter($filter) {
trigger_error('HTMLPurifier->addFilter() is deprecated, use configuration directives in the Filter namespace or Filter.Custom', E_USER_WARNING); trigger_error(
'HTMLPurifier->addFilter() is deprecated, use configuration directives'.
' in the Filter namespace or Filter.Custom',
E_USER_WARNING
);
$this->filters[] = $filter; $this->filters[] = $filter;
} }
/** /**
* Filters an HTML snippet/document to be XSS-free and standards-compliant. * Filters an HTML snippet/document to be XSS-free and standards-compliant.
* *
* @param $html String of HTML to purify * @param string $html String of HTML to purify
* @param $config HTMLPurifier_Config object for this operation, if omitted, * @param HTMLPurifier_Config $config Config object for this operation,
* defaults to the config object specified during this * if omitted, defaults to the config object specified during this
* object's construction. The parameter can also be any type * object's construction. The parameter can also be any type
* that HTMLPurifier_Config::create() supports. * that HTMLPurifier_Config::create() supports.
* @return Purified HTML *
* @return string Purified HTML
*/ */
public function purify($html, $config = null) { public function purify($html, $config = null) {
@ -192,9 +211,12 @@ class HTMLPurifier
/** /**
* Filters an array of HTML snippets * Filters an array of HTML snippets
* @param $config Optional HTMLPurifier_Config object for this operation. *
* @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. * See HTMLPurifier::purify() for more details.
* @return Array of purified HTML *
* @return string[] Array of purified HTML
*/ */
public function purifyArray($array_of_html, $config = null) { public function purifyArray($array_of_html, $config = null) {
$context_array = array(); $context_array = array();
@ -208,9 +230,13 @@ class HTMLPurifier
/** /**
* Singleton for enforcing just one HTML Purifier in your system * Singleton for enforcing just one HTML Purifier in your system
* @param $prototype Optional prototype HTMLPurifier instance to *
* overload singleton with, or HTMLPurifier_Config * @param HTMLPurifier|HTMLPurifier_Config $prototype Optional prototype
* instance to configure the generated version with. * HTMLPurifier instance to overload singleton with,
* or HTMLPurifier_Config instance to configure the
* generated version with.
*
* @return HTMLPurifier
*/ */
public static function instance($prototype = null) { public static function instance($prototype = null) {
if (!self::$instance || $prototype) { if (!self::$instance || $prototype) {
@ -226,6 +252,14 @@ class HTMLPurifier
} }
/** /**
* 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() * @note Backwards compatibility, see instance()
*/ */
public static function getInstance($prototype = null) { public static function getInstance($prototype = null) {

379
library/HTMLPurifier/Config.php
View File

@ -23,7 +23,7 @@ class HTMLPurifier_Config
public $version = '4.5.0'; public $version = '4.5.0';
/** /**
* Bool indicator whether or not to automatically finalize * @var bool indicator whether or not to automatically finalize
* the object if a read operation is done * the object if a read operation is done
*/ */
public $autoFinalize = true; public $autoFinalize = true;
@ -54,7 +54,7 @@ class HTMLPurifier_Config
public $def; public $def;
/** /**
* Indexed array of definitions * @var HTMLPurifier_Definition[] Indexed array of definitions
*/ */
protected $definitions; protected $definitions;
@ -87,10 +87,14 @@ class HTMLPurifier_Config
private $lock; private $lock;
/** /**
* @param $definition HTMLPurifier_ConfigSchema that defines what directives * Constructor
* are allowed. *
* @param HTMLPurifier_ConfigSchema $definition ConfigSchema that defines
* what directives are allowed.
* @param mixed $parent
*/ */
public function __construct($definition, $parent = null) { public function __construct($definition, $parent = null)
{
$parent = $parent ? $parent : $definition->defaultPlist; $parent = $parent ? $parent : $definition->defaultPlist;
$this->plist = new HTMLPurifier_PropertyList($parent); $this->plist = new HTMLPurifier_PropertyList($parent);
$this->def = $definition; // keep a copy around for checking $this->def = $definition; // keep a copy around for checking
@ -99,14 +103,17 @@ class HTMLPurifier_Config
/** /**
* Convenience constructor that creates a config object based on a mixed var * Convenience constructor that creates a config object based on a mixed var
*
* @param mixed $config Variable that defines the state of the config * @param mixed $config Variable that defines the state of the config
* object. Can be: a HTMLPurifier_Config() object, * object. Can be: a HTMLPurifier_Config() object,
* an array of directives based on loadArray(), * an array of directives based on loadArray(),
* or a string filename of an ini file. * or a string filename of an ini file.
* @param HTMLPurifier_ConfigSchema Schema object * @param HTMLPurifier_ConfigSchema $schema Schema object
* @return Configured HTMLPurifier_Config object *
* @return HTMLPurifier_Config Configured object
*/ */
public static function create($config, $schema = null) { public static function create($config, $schema = null)
{
if ($config instanceof HTMLPurifier_Config) { if ($config instanceof HTMLPurifier_Config) {
// pass-through // pass-through
return $config; return $config;
@ -116,18 +123,23 @@ class HTMLPurifier_Config
} else { } else {
$ret = new HTMLPurifier_Config($schema); $ret = new HTMLPurifier_Config($schema);
} }
if (is_string($config)) $ret->loadIni($config); if (is_string($config)) {
$ret->loadIni($config);
}
elseif (is_array($config)) $ret->loadArray($config); elseif (is_array($config)) $ret->loadArray($config);
return $ret; return $ret;
} }
/** /**
* Creates a new config object that inherits from a previous one. * Creates a new config object that inherits from a previous one.
*
* @param HTMLPurifier_Config $config Configuration object to inherit * @param HTMLPurifier_Config $config Configuration object to inherit
* from. * from.
*
* @return HTMLPurifier_Config object with $config as its parent. * @return HTMLPurifier_Config object with $config as its parent.
*/ */
public static function inherit(HTMLPurifier_Config $config) { public static function inherit(HTMLPurifier_Config $config)
{
return new HTMLPurifier_Config($config->def, $config->plist); return new HTMLPurifier_Config($config->def, $config->plist);
} }
@ -135,38 +147,57 @@ class HTMLPurifier_Config
* Convenience constructor that creates a default configuration object. * Convenience constructor that creates a default configuration object.
* @return HTMLPurifier_Config default object. * @return HTMLPurifier_Config default object.
*/ */
public static function createDefault() { public static function createDefault()
{
$definition = HTMLPurifier_ConfigSchema::instance(); $definition = HTMLPurifier_ConfigSchema::instance();
$config = new HTMLPurifier_Config($definition); $config = new HTMLPurifier_Config($definition);
return $config; return $config;
} }
/** /**
* Retreives a value from the configuration. * Retrieves a value from the configuration.
* @param $key String key *
* @param string $key String key
* @param mixed $a
*
* @return mixed
*/ */
public function get($key, $a = null) { public function get($key, $a = null)
{
if ($a !== null) { if ($a !== null) {
$this->triggerError("Using deprecated API: use \$config->get('$key.$a') instead", E_USER_WARNING); $this->triggerError(
"Using deprecated API: use \$config->get('$key.$a') instead",
E_USER_WARNING
);
$key = "$key.$a"; $key = "$key.$a";
} }
if (!$this->finalized) $this->autoFinalize(); if (!$this->finalized) {
$this->autoFinalize();
}
if (!isset($this->def->info[$key])) { if (!isset($this->def->info[$key])) {
// can't add % due to SimpleTest bug // can't add % due to SimpleTest bug
$this->triggerError('Cannot retrieve value of undefined directive ' . htmlspecialchars($key), $this->triggerError(
E_USER_WARNING); 'Cannot retrieve value of undefined directive ' . htmlspecialchars($key),
E_USER_WARNING
);
return; return;
} }
if (isset($this->def->info[$key]->isAlias)) { if (isset($this->def->info[$key]->isAlias)) {
$d = $this->def->info[$key]; $d = $this->def->info[$key];
$this->triggerError('Cannot get value from aliased directive, use real name ' . $d->key, $this->triggerError(
E_USER_ERROR); 'Cannot get value from aliased directive, use real name ' . $d->key,
E_USER_ERROR
);
return; return;
} }
if ($this->lock) { if ($this->lock) {
list($ns) = explode('.', $key); list($ns) = explode('.', $key);
if ($ns !== $this->lock) { if ($ns !== $this->lock) {
$this->triggerError('Cannot get value of namespace ' . $ns . ' when lock for ' . $this->lock . ' is active, this probably indicates a Definition setup method is accessing directives that are not within its namespace', E_USER_ERROR); $this->triggerError(
'Cannot get value of namespace ' . $ns . ' when lock for ' .
$this->lock . ' is active, this probably indicates a Definition setup method is accessing directives that are not within its namespace',
E_USER_ERROR
);
return; return;
} }
} }
@ -174,15 +205,24 @@ class HTMLPurifier_Config
} }
/** /**
* Retreives an array of directives to values from a given namespace * Retrieves an array of directives to values from a given namespace
* @param $namespace String namespace *
* @param string $namespace String namespace
*
* @return array
*/ */
public function getBatch($namespace) { public function getBatch($namespace)
if (!$this->finalized) $this->autoFinalize(); {
if (!$this->finalized) {
$this->autoFinalize();
}
$full = $this->getAll(); $full = $this->getAll();
if (!isset($full[$namespace])) { if (!isset($full[$namespace])) {
$this->triggerError('Cannot retrieve undefined namespace ' . htmlspecialchars($namespace), $this->triggerError(
E_USER_WARNING); 'Cannot retrieve undefined namespace ' .
htmlspecialchars($namespace),
E_USER_WARNING
);
return; return;
} }
return $full[$namespace]; return $full[$namespace];
@ -191,11 +231,15 @@ class HTMLPurifier_Config
/** /**
* Returns a SHA-1 signature of a segment of the configuration object * Returns a SHA-1 signature of a segment of the configuration object
* that uniquely identifies that particular configuration * that uniquely identifies that particular configuration
*
* @param string $namespace Namespace to get serial for
*
* @return string
* @note Revision is handled specially and is removed from the batch * @note Revision is handled specially and is removed from the batch
* before processing! * before processing!
* @param $namespace Namespace to get serial for
*/ */
public function getBatchSerial($namespace) { public function getBatchSerial($namespace)
{
if (empty($this->serials[$namespace])) { if (empty($this->serials[$namespace])) {
$batch = $this->getBatch($namespace); $batch = $this->getBatch($namespace);
unset($batch['DefinitionRev']); unset($batch['DefinitionRev']);
@ -207,8 +251,11 @@ class HTMLPurifier_Config
/** /**
* Returns a SHA-1 signature for the entire configuration object * Returns a SHA-1 signature for the entire configuration object
* that uniquely identifies that particular configuration * that uniquely identifies that particular configuration
*
* @return string
*/ */
public function getSerial() { public function getSerial()
{
if (empty($this->serial)) { if (empty($this->serial)) {
$this->serial = sha1(serialize($this->getAll())); $this->serial = sha1(serialize($this->getAll()));
} }
@ -217,10 +264,14 @@ class HTMLPurifier_Config
/** /**
* Retrieves all directives, organized by namespace * Retrieves all directives, organized by namespace
*
* @warning This is a pretty inefficient function, avoid if you can * @warning This is a pretty inefficient function, avoid if you can
*/ */
public function getAll() { public function getAll()
if (!$this->finalized) $this->autoFinalize(); {
if (!$this->finalized) {
$this->autoFinalize();
}
$ret = array(); $ret = array();
foreach ($this->plist->squash() as $name => $value) { foreach ($this->plist->squash() as $name => $value) {
list($ns, $key) = explode('.', $name, 2); list($ns, $key) = explode('.', $name, 2);
@ -231,10 +282,13 @@ class HTMLPurifier_Config
/** /**
* Sets a value to configuration. * Sets a value to configuration.
* @param $key String key *
* @param $value Mixed value * @param string $key key
* @param mixed $value value
* @param mixed $a
*/ */
public function set($key, $value, $a = null) { public function set($key, $value, $a = null)
{
if (strpos($key, '.') === false) { if (strpos($key, '.') === false) {
$namespace = $key; $namespace = $key;
$directive = $value; $directive = $value;
@ -244,18 +298,25 @@ class HTMLPurifier_Config
} else { } else {
list($namespace) = explode('.', $key); list($namespace) = explode('.', $key);
} }
if ($this->isFinalized('Cannot set directive after finalization')) return; if ($this->isFinalized('Cannot set directive after finalization')) {
return;
}
if (!isset($this->def->info[$key])) { if (!isset($this->def->info[$key])) {
$this->triggerError('Cannot set undefined directive ' . htmlspecialchars($key) . ' to value', $this->triggerError(
E_USER_WARNING); 'Cannot set undefined directive ' . htmlspecialchars($key) . ' to value',
E_USER_WARNING
);
return; return;
} }
$def = $this->def->info[$key]; $def = $this->def->info[$key];
if (isset($def->isAlias)) { if (isset($def->isAlias)) {
if ($this->aliasMode) { if ($this->aliasMode) {
$this->triggerError('Double-aliases not allowed, please fix '. $this->triggerError(
'ConfigSchema bug with' . $key, E_USER_ERROR); 'Double-aliases not allowed, please fix '.
'ConfigSchema bug with' . $key,
E_USER_ERROR
);
return; return;
} }
$this->aliasMode = true; $this->aliasMode = true;
@ -279,7 +340,11 @@ class HTMLPurifier_Config
try { try {
$value = $this->parser->parse($value, $type, $allow_null); $value = $this->parser->parse($value, $type, $allow_null);
} catch (HTMLPurifier_VarParserException $e) { } catch (HTMLPurifier_VarParserException $e) {
$this->triggerError('Value for ' . $key . ' is of invalid type, should be ' . HTMLPurifier_VarParser::getTypeName($type), E_USER_WARNING); $this->triggerError(
'Value for ' . $key . ' is of invalid type, should be ' .
HTMLPurifier_VarParser::getTypeName($type),
E_USER_WARNING
);
return; return;
} }
if (is_string($value) && is_object($def)) { if (is_string($value) && is_object($def)) {
@ -289,8 +354,11 @@ class HTMLPurifier_Config
} }
// check to see if the value is allowed // check to see if the value is allowed
if (isset($def->allowed) && !isset($def->allowed[$value])) { if (isset($def->allowed) && !isset($def->allowed[$value])) {
$this->triggerError('Value not supported, valid values are: ' . $this->triggerError(
$this->_listify($def->allowed), E_USER_WARNING); 'Value not supported, valid values are: ' .
$this->_listify($def->allowed),
E_USER_WARNING
);
return; return;
} }
} }
@ -308,8 +376,13 @@ class HTMLPurifier_Config
/** /**
* Convenience function for error reporting * Convenience function for error reporting
*
* @param array $lookup
*
* @return string
*/ */
private function _listify($lookup) { private function _listify($lookup)
{
$list = array(); $list = array();
foreach ($lookup as $name => $b) $list[] = $name; foreach ($lookup as $name => $b) $list[] = $name;
return implode(', ', $list); return implode(', ', $list);
@ -317,54 +390,67 @@ class HTMLPurifier_Config
/** /**
* Retrieves object reference to the HTML definition. * Retrieves object reference to the HTML definition.
* @param $raw Return a copy that has not been setup yet. Must be *
* @param bool $raw Return a copy that has not been setup yet. Must be
* called before it's been setup, otherwise won't work. * called before it's been setup, otherwise won't work.
* @param $optimized If true, this method may return null, to * @param bool $optimized If true, this method may return null, to
* indicate that a cached version of the modified * indicate that a cached version of the modified
* definition object is available and no further edits * definition object is available and no further edits
* are necessary. Consider using * are necessary. Consider using
* maybeGetRawHTMLDefinition, which is more explicitly * maybeGetRawHTMLDefinition, which is more explicitly
* named, instead. * named, instead.
*
* @return mixed
*/ */
public function getHTMLDefinition($raw = false, $optimized = false) { public function getHTMLDefinition($raw = false, $optimized = false)
{
return $this->getDefinition('HTML', $raw, $optimized); return $this->getDefinition('HTML', $raw, $optimized);
} }
/** /**
* Retrieves object reference to the CSS definition * Retrieves object reference to the CSS definition
* @param $raw Return a copy that has not been setup yet. Must be *
* @param bool $raw Return a copy that has not been setup yet. Must be
* called before it's been setup, otherwise won't work. * called before it's been setup, otherwise won't work.
* @param $optimized If true, this method may return null, to * @param bool $optimized If true, this method may return null, to
* indicate that a cached version of the modified * indicate that a cached version of the modified
* definition object is available and no further edits * definition object is available and no further edits
* are necessary. Consider using * are necessary. Consider using
* maybeGetRawCSSDefinition, which is more explicitly * maybeGetRawCSSDefinition, which is more explicitly
* named, instead. * named, instead.
*
* @return mixed
*/ */
public function getCSSDefinition($raw = false, $optimized = false) { public function getCSSDefinition($raw = false, $optimized = false)
{
return $this->getDefinition('CSS', $raw, $optimized); return $this->getDefinition('CSS', $raw, $optimized);
} }
/** /**
* Retrieves object reference to the URI definition * Retrieves object reference to the URI definition
* @param $raw Return a copy that has not been setup yet. Must be *
* @param bool $raw Return a copy that has not been setup yet. Must be
* called before it's been setup, otherwise won't work. * called before it's been setup, otherwise won't work.
* @param $optimized If true, this method may return null, to * @param bool $optimized If true, this method may return null, to
* indicate that a cached version of the modified * indicate that a cached version of the modified
* definition object is available and no further edits * definition object is available and no further edits
* are necessary. Consider using * are necessary. Consider using
* maybeGetRawURIDefinition, which is more explicitly * maybeGetRawURIDefinition, which is more explicitly
* named, instead. * named, instead.
*
* @return mixed
*/ */
public function getURIDefinition($raw = false, $optimized = false) { public function getURIDefinition($raw = false, $optimized = false)
{
return $this->getDefinition('URI', $raw, $optimized); return $this->getDefinition('URI', $raw, $optimized);
} }
/** /**
* Retrieves a definition * Retrieves a definition
* @param $type Type of definition: HTML, CSS, etc *
* @param $raw Whether or not definition should be returned raw * @param string $type Type of definition: HTML, CSS, etc
* @param $optimized Only has an effect when $raw is true. Whether * @param bool $raw Whether or not definition should be returned raw
* @param bool $optimized Only has an effect when $raw is true. Whether
* or not to return null if the result is already present in * or not to return null if the result is already present in
* the cache. This is off by default for backwards * the cache. This is off by default for backwards
* compatibility reasons, but you need to do things this * compatibility reasons, but you need to do things this
@ -372,12 +458,18 @@ class HTMLPurifier_Config
* Check out enduser-customize.html for more details. * Check out enduser-customize.html for more details.
* We probably won't ever change this default, as much as the * We probably won't ever change this default, as much as the
* maybe semantics is the "right thing to do." * maybe semantics is the "right thing to do."
*
* @throws HTMLPurifier_Exception
* @return mixed
*/ */
public function getDefinition($type, $raw = false, $optimized = false) { public function getDefinition($type, $raw = false, $optimized = false)
{
if ($optimized && !$raw) { if ($optimized && !$raw) {
throw new HTMLPurifier_Exception("Cannot set optimized = true when raw = false"); throw new HTMLPurifier_Exception("Cannot set optimized = true when raw = false");
} }
if (!$this->finalized) $this->autoFinalize(); if (!$this->finalized) {
$this->autoFinalize();
}
// temporarily suspend locks, so we can handle recursive definition calls // temporarily suspend locks, so we can handle recursive definition calls
$lock = $this->lock; $lock = $this->lock;
$this->lock = null; $this->lock = null;
@ -395,7 +487,9 @@ class HTMLPurifier_Config
return $def; return $def;
} else { } else {
$def->setup($this); $def->setup($this);
if ($def->optimized) $cache->add($def, $this); if ($def->optimized) {
$cache->add($def, $this);
}
return $def; return $def;
} }
} }
@ -424,18 +518,27 @@ class HTMLPurifier_Config
if ($optimized) { if ($optimized) {
if (is_null($this->get($type . '.DefinitionID'))) { if (is_null($this->get($type . '.DefinitionID'))) {
// fatally error out if definition ID not set // fatally error out if definition ID not set
throw new HTMLPurifier_Exception("Cannot retrieve raw version without specifying %$type.DefinitionID"); throw new HTMLPurifier_Exception(
"Cannot retrieve raw version without specifying %$type.DefinitionID"
);
} }
} }
if (!empty($this->definitions[$type])) { if (!empty($this->definitions[$type])) {
$def = $this->definitions[$type]; $def = $this->definitions[$type];
if ($def->setup && !$optimized) { if ($def->setup && !$optimized) {
$extra = $this->chatty ? " (try moving this code block earlier in your initialization)" : ""; $extra = $this->chatty ?
throw new HTMLPurifier_Exception("Cannot retrieve raw definition after it has already been setup" . $extra); " (try moving this code block earlier in your initialization)" :
"";
throw new HTMLPurifier_Exception(
"Cannot retrieve raw definition after it has already been setup" .
$extra
);
} }
if ($def->optimized === null) { if ($def->optimized === null) {
$extra = $this->chatty ? " (try flushing your cache)" : ""; $extra = $this->chatty ? " (try flushing your cache)" : "";
throw new HTMLPurifier_Exception("Optimization status of definition is unknown" . $extra); throw new HTMLPurifier_Exception(
"Optimization status of definition is unknown" . $extra
);
} }
if ($def->optimized !== $optimized) { if ($def->optimized !== $optimized) {
$msg = $optimized ? "optimized" : "unoptimized"; $msg = $optimized ? "optimized" : "unoptimized";
@ -475,7 +578,10 @@ class HTMLPurifier_Config
if ($this->chatty) { if ($this->chatty) {
$this->triggerError("Due to a documentation error in previous version of HTML Purifier, your definitions are not being cached. If this is OK, you can remove the %$type.DefinitionRev and %$type.DefinitionID declaration. Otherwise, modify your code to use maybeGetRawDefinition, and test if the returned value is null before making any edits (if it is null, that means that a cached version is available, and no raw operations are necessary). See <a href='http://htmlpurifier.org/docs/enduser-customize.html#optimized'>Customize</a> for more details", E_USER_WARNING); $this->triggerError("Due to a documentation error in previous version of HTML Purifier, your definitions are not being cached. If this is OK, you can remove the %$type.DefinitionRev and %$type.DefinitionID declaration. Otherwise, modify your code to use maybeGetRawDefinition, and test if the returned value is null before making any edits (if it is null, that means that a cached version is available, and no raw operations are necessary). See <a href='http://htmlpurifier.org/docs/enduser-customize.html#optimized'>Customize</a> for more details", E_USER_WARNING);
} else { } else {
$this->triggerError("Useless DefinitionID declaration", E_USER_WARNING); $this->triggerError(
"Useless DefinitionID declaration",
E_USER_WARNING
);
} }
} }
} }
@ -487,7 +593,16 @@ class HTMLPurifier_Config
throw new HTMLPurifier_Exception("The impossible happened!"); throw new HTMLPurifier_Exception("The impossible happened!");
} }
private function initDefinition($type) { /**
* Initialise definition
*
* @param string $type What type of definition to create
*
* @return HTMLPurifier_CSSDefinition|HTMLPurifier_HTMLDefinition|HTMLPurifier_URIDefinition
* @throws HTMLPurifier_Exception
*/
private function initDefinition($type)
{
// quick checks failed, let's create the object // quick checks failed, let's create the object
if ($type == 'HTML') { if ($type == 'HTML') {
$def = new HTMLPurifier_HTMLDefinition(); $def = new HTMLPurifier_HTMLDefinition();
@ -496,35 +611,45 @@ class HTMLPurifier_Config
} elseif ($type == 'URI') { } elseif ($type == 'URI') {
$def = new HTMLPurifier_URIDefinition(); $def = new HTMLPurifier_URIDefinition();
} else { } else {
throw new HTMLPurifier_Exception("Definition of $type type not supported"); throw new HTMLPurifier_Exception(
"Definition of $type type not supported"
);
} }
$this->definitions[$type] = $def; $this->definitions[$type] = $def;
return $def; return $def;
} }
public function maybeGetRawDefinition($name) { public function maybeGetRawDefinition($name)
{
return $this->getDefinition($name, true, true); return $this->getDefinition($name, true, true);
} }
public function maybeGetRawHTMLDefinition() { public function maybeGetRawHTMLDefinition()
{
return $this->getDefinition('HTML', true, true); return $this->getDefinition('HTML', true, true);
} }
public function maybeGetRawCSSDefinition() { public function maybeGetRawCSSDefinition()
{
return $this->getDefinition('CSS', true, true); return $this->getDefinition('CSS', true, true);
} }
public function maybeGetRawURIDefinition() { public function maybeGetRawURIDefinition()
{
return $this->getDefinition('URI', true, true); return $this->getDefinition('URI', true, true);
} }
/** /**
* Loads configuration values from an array with the following structure: * Loads configuration values from an array with the following structure:
* Namespace.Directive => Value * Namespace.Directive => Value
* @param $config_array Configuration associative array *
* @param array $config_array Configuration associative array
*/ */
public function loadArray($config_array) { public function loadArray($config_array)
if ($this->isFinalized('Cannot load directives after finalization')) return; {
if ($this->isFinalized('Cannot load directives after finalization')) {
return;
}
foreach ($config_array as $key => $value) { foreach ($config_array as $key => $value) {
$key = str_replace('_', '.', $key); $key = str_replace('_', '.', $key);
if (strpos($key, '.') !== false) { if (strpos($key, '.') !== false) {
@ -543,14 +668,21 @@ class HTMLPurifier_Config
* Returns a list of array(namespace, directive) for all directives * Returns a list of array(namespace, directive) for all directives
* that are allowed in a web-form context as per an allowed * that are allowed in a web-form context as per an allowed
* namespaces/directives list. * namespaces/directives list.
* @param $allowed List of allowed namespaces/directives *
* @param array $allowed List of allowed namespaces/directives
* @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
*
* @return array
*/ */
public static function getAllowedDirectivesForForm($allowed, $schema = null) { public static function getAllowedDirectivesForForm($allowed, $schema = null)
{
if (!$schema) { if (!$schema) {
$schema = HTMLPurifier_ConfigSchema::instance(); $schema = HTMLPurifier_ConfigSchema::instance();
} }
if ($allowed !== true) { if ($allowed !== true) {
if (is_string($allowed)) $allowed = array($allowed); if (is_string($allowed)) {
$allowed = array($allowed);
}
$allowed_ns = array(); $allowed_ns = array();
$allowed_directives = array(); $allowed_directives = array();
$blacklisted_directives = array(); $blacklisted_directives = array();
@ -572,11 +704,19 @@ class HTMLPurifier_Config
foreach ($schema->info as $key => $def) { foreach ($schema->info as $key => $def) {
list($ns, $directive) = explode('.', $key, 2); list($ns, $directive) = explode('.', $key, 2);
if ($allowed !== true) { if ($allowed !== true) {
if (isset($blacklisted_directives["$ns.$directive"])) continue; if (isset($blacklisted_directives["$ns.$directive"])) {
if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) continue; continue;
}
if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) {
continue;
}
}
if (isset($def->isAlias)) {
continue;
}
if ($directive == 'DefinitionID' || $directive == 'DefinitionRev') {
continue;
} }
if (isset($def->isAlias)) continue;
if ($directive == 'DefinitionID' || $directive == 'DefinitionRev') continue;
$ret[] = array($ns, $directive); $ret[] = array($ns, $directive);
} }
return $ret; return $ret;
@ -585,13 +725,17 @@ class HTMLPurifier_Config
/** /**
* Loads configuration values from $_GET/$_POST that were posted * Loads configuration values from $_GET/$_POST that were posted
* via ConfigForm * via ConfigForm
* @param $array $_GET or $_POST array to import *
* @param $index Index/name that the config variables are in * @param array $array $_GET or $_POST array to import
* @param $allowed List of allowed namespaces/directives * @param string|bool $index Index/name that the config variables are in
* @param $mq_fix Boolean whether or not to enable magic quotes fix * @param array|bool $allowed List of allowed namespaces/directives
* @param $schema Instance of HTMLPurifier_ConfigSchema to use, if not global copy * @param bool $mq_fix Boolean whether or not to enable magic quotes fix
* @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
*
* @return mixed
*/ */
public static function loadArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) { public static function loadArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null)
{
$ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema); $ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema);
$config = HTMLPurifier_Config::create($ret, $schema); $config = HTMLPurifier_Config::create($ret, $schema);
return $config; return $config;
@ -599,9 +743,14 @@ class HTMLPurifier_Config
/** /**
* Merges in configuration values from $_GET/$_POST to object. NOT STATIC. * Merges in configuration values from $_GET/$_POST to object. NOT STATIC.
* @note Same parameters as loadArrayFromForm *
* @param array $array $_GET or $_POST array to import
* @param string|bool $index Index/name that the config variables are in
* @param array|bool $allowed List of allowed namespaces/directives
* @param bool $mq_fix Boolean whether or not to enable magic quotes fix
*/ */
public function mergeArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true) { public function mergeArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true)
{
$ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def); $ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def);
$this->loadArray($ret); $this->loadArray($ret);
} }
@ -609,9 +758,20 @@ class HTMLPurifier_Config
/** /**
* Prepares an array from a form into something usable for the more * Prepares an array from a form into something usable for the more
* strict parts of HTMLPurifier_Config * strict parts of HTMLPurifier_Config
*
* @param array $array $_GET or $_POST array to import
* @param string|bool $index Index/name that the config variables are in
* @param array|bool $allowed List of allowed namespaces/directives
* @param bool $mq_fix Boolean whether or not to enable magic quotes fix
* @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
*
* @return array
*/ */
public static function prepareArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) { public static function prepareArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null)
if ($index !== false) $array = (isset($array[$index]) && is_array($array[$index])) ? $array[$index] : array(); {
if ($index !== false) {
$array = (isset($array[$index]) && is_array($array[$index])) ? $array[$index] : array();
}
$mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc(); $mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc();
$allowed = HTMLPurifier_Config::getAllowedDirectivesForForm($allowed, $schema); $allowed = HTMLPurifier_Config::getAllowedDirectivesForForm($allowed, $schema);
@ -623,7 +783,9 @@ class HTMLPurifier_Config
$ret[$ns][$directive] = null; $ret[$ns][$directive] = null;
continue; continue;
} }
if (!isset($array[$skey])) continue; if (!isset($array[$skey])) {
continue;
}
$value = $mq ? stripslashes($array[$skey]) : $array[$skey]; $value = $mq ? stripslashes($array[$skey]) : $array[$skey];
$ret[$ns][$directive] = $value; $ret[$ns][$directive] = $value;
} }
@ -632,19 +794,27 @@ class HTMLPurifier_Config
/** /**
* Loads configuration values from an ini file * Loads configuration values from an ini file
* @param $filename Name of ini file *
* @param string $filename Name of ini file
*/ */
public function loadIni($filename) { public function loadIni($filename)
if ($this->isFinalized('Cannot load directives after finalization')) return; {
if ($this->isFinalized('Cannot load directives after finalization')) {
return;
}
$array = parse_ini_file($filename, true); $array = parse_ini_file($filename, true);
$this->loadArray($array); $this->loadArray($array);
} }
/** /**
* Checks whether or not the configuration object is finalized. * Checks whether or not the configuration object is finalized.
* @param $error String error message, or false for no error *
* @param string|bool $error String error message, or false for no error
*
* @return bool
*/ */
public function isFinalized($error = false) { public function isFinalized($error = false)
{
if ($this->finalized && $error) { if ($this->finalized && $error) {
$this->triggerError($error, E_USER_ERROR); $this->triggerError($error, E_USER_ERROR);
} }
@ -655,7 +825,8 @@ class HTMLPurifier_Config
* Finalizes configuration only if auto finalize is on and not * Finalizes configuration only if auto finalize is on and not
* already finalized * already finalized
*/ */
public function autoFinalize() { public function autoFinalize()
{
if ($this->autoFinalize) { if ($this->autoFinalize) {
$this->finalize(); $this->finalize();
} else { } else {
@ -666,7 +837,8 @@ class HTMLPurifier_Config
/** /**
* Finalizes a configuration object, prohibiting further change * Finalizes a configuration object, prohibiting further change
*/ */
public function finalize() { public function finalize()
{
$this->finalized = true; $this->finalized = true;
$this->parser = null; $this->parser = null;
} }
@ -674,8 +846,12 @@ class HTMLPurifier_Config
/** /**
* Produces a nicely formatted error message by supplying the * Produces a nicely formatted error message by supplying the
* stack frame information OUTSIDE of HTMLPurifier_Config. * stack frame information OUTSIDE of HTMLPurifier_Config.
*
* @param string $msg An error message
* @param int $no An error number
*/ */
protected function triggerError($msg, $no) { protected function triggerError($msg, $no)
{
// determine previous stack frame // determine previous stack frame
$extra = ''; $extra = '';
if ($this->chatty) { if ($this->chatty) {
@ -697,8 +873,11 @@ class HTMLPurifier_Config
/** /**
* Returns a serialized form of the configuration object that can * Returns a serialized form of the configuration object that can
* be reconstituted. * be reconstituted.
*
* @return string
*/ */
public function serialize() { public function serialize()
{
$this->getDefinition('HTML'); $this->getDefinition('HTML');
$this->getDefinition('CSS'); $this->getDefinition('CSS');
$this->getDefinition('URI'); $this->getDefinition('URI');

34
library/HTMLPurifier/DefinitionCache/Decorator.php
View File

@ -5,6 +5,7 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach
/** /**
* Cache object we are decorating * Cache object we are decorating
* @var HTMLPurifier_DefinitionCache
*/ */
public $cache; public $cache;
@ -12,9 +13,13 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach
/** /**
* Lazy decorator function * Lazy decorator function
* @param $cache Reference to cache object to decorate *
* @param HTMLPurifier_DefinitionCache $cache Reference to cache object to decorate
*
* @return HTMLPurifier_DefinitionCache_Decorator
*/ */
public function decorate(&$cache) { public function decorate(&$cache)
{
$decorator = $this->copy(); $decorator = $this->copy();
// reference is necessary for mocks in PHP 4 // reference is necessary for mocks in PHP 4
$decorator->cache =& $cache; $decorator->cache =& $cache;
@ -25,38 +30,45 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach
/** /**
* Cross-compatible clone substitute * Cross-compatible clone substitute
*/ */
public function copy() { public function copy()
{
return new HTMLPurifier_DefinitionCache_Decorator(); return new HTMLPurifier_DefinitionCache_Decorator();
} }
public function add($def, $config) { public function add($def, $config)
{
return $this->cache->add($def, $config); return $this->cache->add($def, $config);
} }
public function set($def, $config) { public function set($def, $config)
{
return $this->cache->set($def, $config); return $this->cache->set($def, $config);
} }
public function replace($def, $config) { public function replace($def, $config)
{
return $this->cache->replace($def, $config); return $this->cache->replace($def, $config);
} }
public function get($config) { public function get($config)
{
return $this->cache->get($config); return $this->cache->get($config);
} }
public function remove($config) { public function remove($config)
{
return $this->cache->remove($config); return $this->cache->remove($config);
} }
public function flush($config) { public function flush($config)
{
return $this->cache->flush($config); return $this->cache->flush($config);
} }
public function cleanup($config) { public function cleanup($config)
{
return $this->cache->cleanup($config); return $this->cache->cleanup($config);
} }
} }
// vim: et sw=4 sts=4 // vim: et sw=4 sts=4

31
library/HTMLPurifier/DefinitionCacheFactory.php
View File

@ -8,19 +8,26 @@ class HTMLPurifier_DefinitionCacheFactory
protected $caches = array('Serializer' => array()); protected $caches = array('Serializer' => array());
protected $implementations = array(); protected $implementations = array();
/**
* @var HTMLPurifier_DefinitionCache_Decorator[]
*/
protected $decorators = array(); protected $decorators = array();
/** /**
* Initialize default decorators * Initialize default decorators
*/ */
public function setup() { public function setup()
{
$this->addDecorator('Cleanup'); $this->addDecorator('Cleanup');
} }
/** /**
* Retrieves an instance of global definition cache factory. * Retrieves an instance of global definition cache factory.
*
* @return HTMLPurifier_DefinitionCacheFactory
*/ */
public static function instance($prototype = null) { public static function instance($prototype = null)
{
static $instance; static $instance;
if ($prototype !== null) { if ($prototype !== null) {
$instance = $prototype; $instance = $prototype;
@ -33,19 +40,22 @@ class HTMLPurifier_DefinitionCacheFactory
/** /**
* Registers a new definition cache object * Registers a new definition cache object
* @param $short Short name of cache object, for reference * @param string $short Short name of cache object, for reference
* @param $long Full class name of cache object, for construction * @param string $long Full class name of cache object, for construction
*/ */
public function register($short, $long) { public function register($short, $long)
{
$this->implementations[$short] = $long; $this->implementations[$short] = $long;
} }
/** /**
* Factory method that creates a cache object based on configuration * Factory method that creates a cache object based on configuration
* @param $name Name of definitions handled by cache *
* @param $config Instance of HTMLPurifier_Config * @param string $name Name of definitions handled by cache
* @param HTMLPurifier_Config $config Config instance
*/ */
public function create($type, $config) { public function create($type, $config)
{
$method = $config->get('Cache.DefinitionImpl'); $method = $config->get('Cache.DefinitionImpl');
if ($method === null) { if ($method === null) {
return new HTMLPurifier_DefinitionCache_Null($type); return new HTMLPurifier_DefinitionCache_Null($type);
@ -76,9 +86,10 @@ class HTMLPurifier_DefinitionCacheFactory
/** /**
* Registers a decorator to add to all new cache objects * Registers a decorator to add to all new cache objects
* @param * @param HTMLPurifier_DefinitionCache_Decorator|string $decorator An instance or the name of a decorator
*/ */
public function addDecorator($decorator) { public function addDecorator($decorator)
{
if (is_string($decorator)) { if (is_string($decorator)) {
$class = "HTMLPurifier_DefinitionCache_Decorator_$decorator"; $class = "HTMLPurifier_DefinitionCache_Decorator_$decorator";
$decorator = new $class; $decorator = new $class;