From 29a3c70370c15c36dd3307a1d4932aa66af27717 Mon Sep 17 00:00:00 2001 From: Synchro Date: Tue, 16 Jul 2013 14:20:01 +0200 Subject: [PATCH] A bunch of PHPdoc and php codesniffer corrections - no functional code changes --- library/HTMLPurifier.php | 76 +++- library/HTMLPurifier/Config.php | 411 +++++++++++++----- .../DefinitionCache/Decorator.php | 34 +- .../HTMLPurifier/DefinitionCacheFactory.php | 31 +- 4 files changed, 394 insertions(+), 158 deletions(-) diff --git a/library/HTMLPurifier.php b/library/HTMLPurifier.php index fe5a9d50..02fb0902 100644 --- a/library/HTMLPurifier.php +++ b/library/HTMLPurifier.php @@ -54,34 +54,47 @@ class HTMLPurifier { - /** Version of HTML Purifier */ + /** + * @var string Version of HTML Purifier + */ public $version = '4.5.0'; - /** Constant with version of HTML Purifier */ + /** + * Constant with version of HTML Purifier + */ const VERSION = '4.5.0'; - /** Global configuration object */ + /** + * @var HTMLPurifier_Config Global configuration object + */ 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(); - /** Single instance of HTML Purifier */ + /** + * @var HTMLPurifier Single instance of HTML Purifier + */ private static $instance; protected $strategy, $generator; /** - * Resultant HTMLPurifier_Context of last run purification. Is an array - * of contexts if the last called method was purifyArray(). + * @var HTMLPurifier_Context Resultant context of last run purification. + * Is an array of contexts if the last called method was purifyArray(). */ public $context; /** * Initializes the purifier. - * @param $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). + * + * @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. */ @@ -95,22 +108,28 @@ class HTMLPurifier /** * 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) { - 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; } /** * Filters an HTML snippet/document to be XSS-free and standards-compliant. * - * @param $html String of HTML to purify - * @param $config HTMLPurifier_Config object for this operation, if omitted, - * defaults to the config object specified during this + * @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 Purified HTML + * + * @return string Purified HTML */ public function purify($html, $config = null) { @@ -192,9 +211,12 @@ class HTMLPurifier /** * 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. - * @return Array of purified HTML + * + * @return string[] Array of purified HTML */ public function purifyArray($array_of_html, $config = null) { $context_array = array(); @@ -208,9 +230,13 @@ class HTMLPurifier /** * Singleton for enforcing just one HTML Purifier in your system - * @param $prototype Optional prototype HTMLPurifier instance to - * overload singleton with, or HTMLPurifier_Config - * instance to configure the generated version with. + * + * @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) { @@ -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() */ public static function getInstance($prototype = null) { diff --git a/library/HTMLPurifier/Config.php b/library/HTMLPurifier/Config.php index fbc5f75e..695b6d07 100644 --- a/library/HTMLPurifier/Config.php +++ b/library/HTMLPurifier/Config.php @@ -23,7 +23,7 @@ class HTMLPurifier_Config 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 */ public $autoFinalize = true; @@ -54,7 +54,7 @@ class HTMLPurifier_Config public $def; /** - * Indexed array of definitions + * @var HTMLPurifier_Definition[] Indexed array of definitions */ protected $definitions; @@ -87,10 +87,14 @@ class HTMLPurifier_Config private $lock; /** - * @param $definition HTMLPurifier_ConfigSchema that defines what directives - * are allowed. + * Constructor + * + * @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; $this->plist = new HTMLPurifier_PropertyList($parent); $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 + * * @param mixed $config Variable that defines the state of the config * object. Can be: a HTMLPurifier_Config() object, * an array of directives based on loadArray(), * or a string filename of an ini file. - * @param HTMLPurifier_ConfigSchema Schema object - * @return Configured HTMLPurifier_Config object + * @param HTMLPurifier_ConfigSchema $schema Schema 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) { // pass-through return $config; @@ -116,18 +123,23 @@ class HTMLPurifier_Config } else { $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); return $ret; } /** * Creates a new config object that inherits from a previous one. + * * @param HTMLPurifier_Config $config Configuration object to inherit * from. + * * @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); } @@ -135,38 +147,57 @@ class HTMLPurifier_Config * Convenience constructor that creates a default configuration object. * @return HTMLPurifier_Config default object. */ - public static function createDefault() { + public static function createDefault() + { $definition = HTMLPurifier_ConfigSchema::instance(); $config = new HTMLPurifier_Config($definition); return $config; } /** - * Retreives a value from the configuration. - * @param $key String key + * Retrieves a value from the configuration. + * + * @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) { - $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"; } - if (!$this->finalized) $this->autoFinalize(); + if (!$this->finalized) { + $this->autoFinalize(); + } if (!isset($this->def->info[$key])) { // can't add % due to SimpleTest bug - $this->triggerError('Cannot retrieve value of undefined directive ' . htmlspecialchars($key), - E_USER_WARNING); + $this->triggerError( + 'Cannot retrieve value of undefined directive ' . htmlspecialchars($key), + E_USER_WARNING + ); return; } if (isset($this->def->info[$key]->isAlias)) { $d = $this->def->info[$key]; - $this->triggerError('Cannot get value from aliased directive, use real name ' . $d->key, - E_USER_ERROR); + $this->triggerError( + 'Cannot get value from aliased directive, use real name ' . $d->key, + E_USER_ERROR + ); return; } if ($this->lock) { list($ns) = explode('.', $key); 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; } } @@ -174,15 +205,24 @@ class HTMLPurifier_Config } /** - * Retreives an array of directives to values from a given namespace - * @param $namespace String namespace + * Retrieves an array of directives to values from a given namespace + * + * @param string $namespace String namespace + * + * @return array */ - public function getBatch($namespace) { - if (!$this->finalized) $this->autoFinalize(); + public function getBatch($namespace) + { + if (!$this->finalized) { + $this->autoFinalize(); + } $full = $this->getAll(); if (!isset($full[$namespace])) { - $this->triggerError('Cannot retrieve undefined namespace ' . htmlspecialchars($namespace), - E_USER_WARNING); + $this->triggerError( + 'Cannot retrieve undefined namespace ' . + htmlspecialchars($namespace), + E_USER_WARNING + ); return; } return $full[$namespace]; @@ -191,11 +231,15 @@ class HTMLPurifier_Config /** * Returns a SHA-1 signature of a segment of the configuration object * 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 * before processing! - * @param $namespace Namespace to get serial for */ - public function getBatchSerial($namespace) { + public function getBatchSerial($namespace) + { if (empty($this->serials[$namespace])) { $batch = $this->getBatch($namespace); unset($batch['DefinitionRev']); @@ -207,8 +251,11 @@ class HTMLPurifier_Config /** * Returns a SHA-1 signature for the entire configuration object * that uniquely identifies that particular configuration + * + * @return string */ - public function getSerial() { + public function getSerial() + { if (empty($this->serial)) { $this->serial = sha1(serialize($this->getAll())); } @@ -217,10 +264,14 @@ class HTMLPurifier_Config /** * Retrieves all directives, organized by namespace + * * @warning This is a pretty inefficient function, avoid if you can */ - public function getAll() { - if (!$this->finalized) $this->autoFinalize(); + public function getAll() + { + if (!$this->finalized) { + $this->autoFinalize(); + } $ret = array(); foreach ($this->plist->squash() as $name => $value) { list($ns, $key) = explode('.', $name, 2); @@ -231,10 +282,13 @@ class HTMLPurifier_Config /** * 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) { $namespace = $key; $directive = $value; @@ -244,18 +298,25 @@ class HTMLPurifier_Config } else { 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])) { - $this->triggerError('Cannot set undefined directive ' . htmlspecialchars($key) . ' to value', - E_USER_WARNING); + $this->triggerError( + 'Cannot set undefined directive ' . htmlspecialchars($key) . ' to value', + E_USER_WARNING + ); return; } $def = $this->def->info[$key]; if (isset($def->isAlias)) { if ($this->aliasMode) { - $this->triggerError('Double-aliases not allowed, please fix '. - 'ConfigSchema bug with' . $key, E_USER_ERROR); + $this->triggerError( + 'Double-aliases not allowed, please fix '. + 'ConfigSchema bug with' . $key, + E_USER_ERROR + ); return; } $this->aliasMode = true; @@ -279,7 +340,11 @@ class HTMLPurifier_Config try { $value = $this->parser->parse($value, $type, $allow_null); } 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; } if (is_string($value) && is_object($def)) { @@ -289,8 +354,11 @@ class HTMLPurifier_Config } // check to see if the value is allowed if (isset($def->allowed) && !isset($def->allowed[$value])) { - $this->triggerError('Value not supported, valid values are: ' . - $this->_listify($def->allowed), E_USER_WARNING); + $this->triggerError( + 'Value not supported, valid values are: ' . + $this->_listify($def->allowed), + E_USER_WARNING + ); return; } } @@ -308,8 +376,13 @@ class HTMLPurifier_Config /** * Convenience function for error reporting + * + * @param array $lookup + * + * @return string */ - private function _listify($lookup) { + private function _listify($lookup) + { $list = array(); foreach ($lookup as $name => $b) $list[] = $name; return implode(', ', $list); @@ -317,54 +390,67 @@ class HTMLPurifier_Config /** * 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. - * @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 * definition object is available and no further edits * are necessary. Consider using * maybeGetRawHTMLDefinition, which is more explicitly * named, instead. + * + * @return mixed */ - public function getHTMLDefinition($raw = false, $optimized = false) { + public function getHTMLDefinition($raw = false, $optimized = false) + { return $this->getDefinition('HTML', $raw, $optimized); } /** * 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. - * @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 * definition object is available and no further edits * are necessary. Consider using * maybeGetRawCSSDefinition, which is more explicitly * named, instead. + * + * @return mixed */ - public function getCSSDefinition($raw = false, $optimized = false) { + public function getCSSDefinition($raw = false, $optimized = false) + { return $this->getDefinition('CSS', $raw, $optimized); } /** * 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. - * @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 * definition object is available and no further edits * are necessary. Consider using * maybeGetRawURIDefinition, which is more explicitly * named, instead. + * + * @return mixed */ - public function getURIDefinition($raw = false, $optimized = false) { + public function getURIDefinition($raw = false, $optimized = false) + { return $this->getDefinition('URI', $raw, $optimized); } /** * Retrieves a definition - * @param $type Type of definition: HTML, CSS, etc - * @param $raw Whether or not definition should be returned raw - * @param $optimized Only has an effect when $raw is true. Whether + * + * @param string $type Type of definition: HTML, CSS, etc + * @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 * the cache. This is off by default for backwards * compatibility reasons, but you need to do things this @@ -372,12 +458,18 @@ class HTMLPurifier_Config * Check out enduser-customize.html for more details. * We probably won't ever change this default, as much as the * 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) { 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 $lock = $this->lock; $this->lock = null; @@ -395,7 +487,9 @@ class HTMLPurifier_Config return $def; } else { $def->setup($this); - if ($def->optimized) $cache->add($def, $this); + if ($def->optimized) { + $cache->add($def, $this); + } return $def; } } @@ -424,18 +518,27 @@ class HTMLPurifier_Config if ($optimized) { if (is_null($this->get($type . '.DefinitionID'))) { // 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])) { $def = $this->definitions[$type]; if ($def->setup && !$optimized) { - $extra = $this->chatty ? " (try moving this code block earlier in your initialization)" : ""; - throw new HTMLPurifier_Exception("Cannot retrieve raw definition after it has already been setup" . $extra); + $extra = $this->chatty ? + " (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) { $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) { $msg = $optimized ? "optimized" : "unoptimized"; @@ -475,7 +578,10 @@ class HTMLPurifier_Config 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 Customize for more details", E_USER_WARNING); } 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!"); } - 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 if ($type == 'HTML') { $def = new HTMLPurifier_HTMLDefinition(); @@ -496,35 +611,45 @@ class HTMLPurifier_Config } elseif ($type == 'URI') { $def = new HTMLPurifier_URIDefinition(); } 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; return $def; } - public function maybeGetRawDefinition($name) { + public function maybeGetRawDefinition($name) + { return $this->getDefinition($name, true, true); } - public function maybeGetRawHTMLDefinition() { + public function maybeGetRawHTMLDefinition() + { return $this->getDefinition('HTML', true, true); } - public function maybeGetRawCSSDefinition() { + public function maybeGetRawCSSDefinition() + { return $this->getDefinition('CSS', true, true); } - public function maybeGetRawURIDefinition() { + public function maybeGetRawURIDefinition() + { return $this->getDefinition('URI', true, true); } /** * Loads configuration values from an array with the following structure: * Namespace.Directive => Value - * @param $config_array Configuration associative array + * + * @param array $config_array Configuration associative array */ - public function loadArray($config_array) { - if ($this->isFinalized('Cannot load directives after finalization')) return; + public function loadArray($config_array) + { + if ($this->isFinalized('Cannot load directives after finalization')) { + return; + } foreach ($config_array as $key => $value) { $key = str_replace('_', '.', $key); if (strpos($key, '.') !== false) { @@ -543,40 +668,55 @@ class HTMLPurifier_Config * Returns a list of array(namespace, directive) for all directives * that are allowed in a web-form context as per an allowed * 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) { $schema = HTMLPurifier_ConfigSchema::instance(); } if ($allowed !== true) { - if (is_string($allowed)) $allowed = array($allowed); - $allowed_ns = array(); - $allowed_directives = array(); - $blacklisted_directives = array(); - foreach ($allowed as $ns_or_directive) { - if (strpos($ns_or_directive, '.') !== false) { - // directive - if ($ns_or_directive[0] == '-') { - $blacklisted_directives[substr($ns_or_directive, 1)] = true; - } else { - $allowed_directives[$ns_or_directive] = true; - } - } else { - // namespace - $allowed_ns[$ns_or_directive] = true; - } - } + if (is_string($allowed)) { + $allowed = array($allowed); + } + $allowed_ns = array(); + $allowed_directives = array(); + $blacklisted_directives = array(); + foreach ($allowed as $ns_or_directive) { + if (strpos($ns_or_directive, '.') !== false) { + // directive + if ($ns_or_directive[0] == '-') { + $blacklisted_directives[substr($ns_or_directive, 1)] = true; + } else { + $allowed_directives[$ns_or_directive] = true; + } + } else { + // namespace + $allowed_ns[$ns_or_directive] = true; + } + } } $ret = array(); foreach ($schema->info as $key => $def) { list($ns, $directive) = explode('.', $key, 2); if ($allowed !== true) { - if (isset($blacklisted_directives["$ns.$directive"])) continue; - if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) continue; + if (isset($blacklisted_directives["$ns.$directive"])) { + 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); } return $ret; @@ -585,13 +725,17 @@ class HTMLPurifier_Config /** * Loads configuration values from $_GET/$_POST that were posted * via ConfigForm - * @param $array $_GET or $_POST array to import - * @param $index Index/name that the config variables are in - * @param $allowed List of allowed namespaces/directives - * @param $mq_fix Boolean whether or not to enable magic quotes fix - * @param $schema Instance of HTMLPurifier_ConfigSchema to use, if not global copy + * + * @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 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); $config = HTMLPurifier_Config::create($ret, $schema); return $config; @@ -599,9 +743,14 @@ class HTMLPurifier_Config /** * 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); $this->loadArray($ret); } @@ -609,9 +758,20 @@ class HTMLPurifier_Config /** * Prepares an array from a form into something usable for the more * 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) { - if ($index !== false) $array = (isset($array[$index]) && is_array($array[$index])) ? $array[$index] : array(); + 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(); + } $mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc(); $allowed = HTMLPurifier_Config::getAllowedDirectivesForForm($allowed, $schema); @@ -623,7 +783,9 @@ class HTMLPurifier_Config $ret[$ns][$directive] = null; continue; } - if (!isset($array[$skey])) continue; + if (!isset($array[$skey])) { + continue; + } $value = $mq ? stripslashes($array[$skey]) : $array[$skey]; $ret[$ns][$directive] = $value; } @@ -632,19 +794,27 @@ class HTMLPurifier_Config /** * Loads configuration values from an ini file - * @param $filename Name of ini file + * + * @param string $filename Name of ini file */ - public function loadIni($filename) { - if ($this->isFinalized('Cannot load directives after finalization')) return; + public function loadIni($filename) + { + if ($this->isFinalized('Cannot load directives after finalization')) { + return; + } $array = parse_ini_file($filename, true); $this->loadArray($array); } /** * 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) { $this->triggerError($error, E_USER_ERROR); } @@ -655,7 +825,8 @@ class HTMLPurifier_Config * Finalizes configuration only if auto finalize is on and not * already finalized */ - public function autoFinalize() { + public function autoFinalize() + { if ($this->autoFinalize) { $this->finalize(); } else { @@ -666,7 +837,8 @@ class HTMLPurifier_Config /** * Finalizes a configuration object, prohibiting further change */ - public function finalize() { + public function finalize() + { $this->finalized = true; $this->parser = null; } @@ -674,8 +846,12 @@ class HTMLPurifier_Config /** * Produces a nicely formatted error message by supplying the * 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 $extra = ''; if ($this->chatty) { @@ -697,8 +873,11 @@ class HTMLPurifier_Config /** * Returns a serialized form of the configuration object that can * be reconstituted. + * + * @return string */ - public function serialize() { + public function serialize() + { $this->getDefinition('HTML'); $this->getDefinition('CSS'); $this->getDefinition('URI'); diff --git a/library/HTMLPurifier/DefinitionCache/Decorator.php b/library/HTMLPurifier/DefinitionCache/Decorator.php index b0fb6d0c..e8b0dbec 100644 --- a/library/HTMLPurifier/DefinitionCache/Decorator.php +++ b/library/HTMLPurifier/DefinitionCache/Decorator.php @@ -5,6 +5,7 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach /** * Cache object we are decorating + * @var HTMLPurifier_DefinitionCache */ public $cache; @@ -12,9 +13,13 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach /** * 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(); // reference is necessary for mocks in PHP 4 $decorator->cache =& $cache; @@ -25,38 +30,45 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach /** * Cross-compatible clone substitute */ - public function copy() { + public function copy() + { return new HTMLPurifier_DefinitionCache_Decorator(); } - public function add($def, $config) { + public function 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); } - public function replace($def, $config) { + public function replace($def, $config) + { return $this->cache->replace($def, $config); } - public function get($config) { + public function get($config) + { return $this->cache->get($config); } - public function remove($config) { + public function remove($config) + { return $this->cache->remove($config); } - public function flush($config) { + public function flush($config) + { return $this->cache->flush($config); } - public function cleanup($config) { + public function cleanup($config) + { return $this->cache->cleanup($config); } - } // vim: et sw=4 sts=4 diff --git a/library/HTMLPurifier/DefinitionCacheFactory.php b/library/HTMLPurifier/DefinitionCacheFactory.php index a6ead628..faa12899 100644 --- a/library/HTMLPurifier/DefinitionCacheFactory.php +++ b/library/HTMLPurifier/DefinitionCacheFactory.php @@ -8,19 +8,26 @@ class HTMLPurifier_DefinitionCacheFactory protected $caches = array('Serializer' => array()); protected $implementations = array(); + /** + * @var HTMLPurifier_DefinitionCache_Decorator[] + */ protected $decorators = array(); /** * Initialize default decorators */ - public function setup() { + public function setup() + { $this->addDecorator('Cleanup'); } /** * 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; if ($prototype !== null) { $instance = $prototype; @@ -33,19 +40,22 @@ class HTMLPurifier_DefinitionCacheFactory /** * Registers a new definition cache object - * @param $short Short name of cache object, for reference - * @param $long Full class name of cache object, for construction + * @param string $short Short name of cache object, for reference + * @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; } /** * 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'); if ($method === null) { return new HTMLPurifier_DefinitionCache_Null($type); @@ -76,9 +86,10 @@ class HTMLPurifier_DefinitionCacheFactory /** * 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)) { $class = "HTMLPurifier_DefinitionCache_Decorator_$decorator"; $decorator = new $class;