4 * Configuration object that triggers customizable behavior.
6 * @warning This class is strongly defined: that means that the class
7 * will fail if an undefined directive is retrieved or set.
9 * @note Many classes that could (although many times don't) use the
10 * configuration object make it a mandatory parameter. This is
11 * because a configuration object should always be forwarded,
12 * otherwise, you run the risk of missing a parameter and then
13 * being stumped when a configuration directive doesn't work.
15 * @todo Reconsider some of the public member variables
17 class HTMLPurifier_Config
21 * HTML Purifier's version
23 public $version = '4.5.0';
26 * @var bool indicator whether or not to automatically finalize
27 * the object if a read operation is done
29 public $autoFinalize = true;
31 // protected member variables
34 * Namespace indexed array of serials for specific namespaces (see
35 * getSerial() for more info).
37 protected $serials = array();
40 * Serial for entire configuration object
45 * Parser for variables
47 protected $parser = null;
50 * Reference HTMLPurifier_ConfigSchema for value checking
51 * @note This is public for introspective purposes. Please don't
57 * @var HTMLPurifier_Definition[] Indexed array of definitions
59 protected $definitions;
62 * Bool indicator whether or not config is finalized
64 protected $finalized = false;
67 * Property list containing configuration directives.
72 * Whether or not a set is taking place due to an
78 * Set to false if you do not want line and file numbers in errors
79 * (useful when unit testing). This will also compress some errors
82 public $chatty = true;
85 * Current lock; only gets to this namespace are allowed.
92 * @param HTMLPurifier_ConfigSchema $definition ConfigSchema that defines
93 * what directives are allowed.
94 * @param mixed $parent
96 public function __construct($definition, $parent = null)
98 $parent = $parent ?
$parent : $definition->defaultPlist
;
99 $this->plist
= new HTMLPurifier_PropertyList($parent);
100 $this->def
= $definition; // keep a copy around for checking
101 $this->parser
= new HTMLPurifier_VarParser_Flexible();
105 * Convenience constructor that creates a config object based on a mixed var
107 * @param mixed $config Variable that defines the state of the config
108 * object. Can be: a HTMLPurifier_Config() object,
109 * an array of directives based on loadArray(),
110 * or a string filename of an ini file.
111 * @param HTMLPurifier_ConfigSchema $schema Schema object
113 * @return HTMLPurifier_Config Configured object
115 public static function create($config, $schema = null)
117 if ($config instanceof HTMLPurifier_Config
) {
122 $ret = HTMLPurifier_Config
::createDefault();
124 $ret = new HTMLPurifier_Config($schema);
126 if (is_string($config)) {
127 $ret->loadIni($config);
129 elseif (is_array($config)) $ret->loadArray($config);
134 * Creates a new config object that inherits from a previous one.
136 * @param HTMLPurifier_Config $config Configuration object to inherit
139 * @return HTMLPurifier_Config object with $config as its parent.
141 public static function inherit(HTMLPurifier_Config
$config)
143 return new HTMLPurifier_Config($config->def
, $config->plist
);
147 * Convenience constructor that creates a default configuration object.
148 * @return HTMLPurifier_Config default object.
150 public static function createDefault()
152 $definition = HTMLPurifier_ConfigSchema
::instance();
153 $config = new HTMLPurifier_Config($definition);
158 * Retrieves a value from the configuration.
160 * @param string $key String key
165 public function get($key, $a = null)
169 "Using deprecated API: use \$config->get('$key.$a') instead",
174 if (!$this->finalized
) {
175 $this->autoFinalize();
177 if (!isset($this->def
->info
[$key])) {
178 // can't add % due to SimpleTest bug
180 'Cannot retrieve value of undefined directive ' . htmlspecialchars($key),
185 if (isset($this->def
->info
[$key]->isAlias
)) {
186 $d = $this->def
->info
[$key];
188 'Cannot get value from aliased directive, use real name ' . $d->key
,
194 list($ns) = explode('.', $key);
195 if ($ns !== $this->lock
) {
197 'Cannot get value of namespace ' . $ns . ' when lock for ' .
198 $this->lock
. ' is active, this probably indicates a Definition setup method is accessing directives that are not within its namespace',
204 return $this->plist
->get($key);
208 * Retrieves an array of directives to values from a given namespace
210 * @param string $namespace String namespace
214 public function getBatch($namespace)
216 if (!$this->finalized
) {
217 $this->autoFinalize();
219 $full = $this->getAll();
220 if (!isset($full[$namespace])) {
222 'Cannot retrieve undefined namespace ' .
223 htmlspecialchars($namespace),
228 return $full[$namespace];
232 * Returns a SHA-1 signature of a segment of the configuration object
233 * that uniquely identifies that particular configuration
235 * @param string $namespace Namespace to get serial for
238 * @note Revision is handled specially and is removed from the batch
241 public function getBatchSerial($namespace)
243 if (empty($this->serials
[$namespace])) {
244 $batch = $this->getBatch($namespace);
245 unset($batch['DefinitionRev']);
246 $this->serials
[$namespace] = sha1(serialize($batch));
248 return $this->serials
[$namespace];
252 * Returns a SHA-1 signature for the entire configuration object
253 * that uniquely identifies that particular configuration
257 public function getSerial()
259 if (empty($this->serial
)) {
260 $this->serial
= sha1(serialize($this->getAll()));
262 return $this->serial
;
266 * Retrieves all directives, organized by namespace
268 * @warning This is a pretty inefficient function, avoid if you can
270 public function getAll()
272 if (!$this->finalized
) {
273 $this->autoFinalize();
276 foreach ($this->plist
->squash() as $name => $value) {
277 list($ns, $key) = explode('.', $name, 2);
278 $ret[$ns][$key] = $value;
284 * Sets a value to configuration.
286 * @param string $key key
287 * @param mixed $value value
290 public function set($key, $value, $a = null)
292 if (strpos($key, '.') === false) {
296 $key = "$key.$directive";
297 $this->triggerError("Using deprecated API: use \$config->set('$key', ...) instead", E_USER_NOTICE
);
299 list($namespace) = explode('.', $key);
301 if ($this->isFinalized('Cannot set directive after finalization')) {
304 if (!isset($this->def
->info
[$key])) {
306 'Cannot set undefined directive ' . htmlspecialchars($key) . ' to value',
311 $def = $this->def
->info
[$key];
313 if (isset($def->isAlias
)) {
314 if ($this->aliasMode
) {
316 'Double-aliases not allowed, please fix '.
317 'ConfigSchema bug with' . $key,
322 $this->aliasMode
= true;
323 $this->set($def->key
, $value);
324 $this->aliasMode
= false;
325 $this->triggerError("$key is an alias, preferred directive name is {$def->key}", E_USER_NOTICE
);
329 // Raw type might be negative when using the fully optimized form
330 // of stdclass, which indicates allow_null == true
331 $rtype = is_int($def) ?
$def : $def->type
;
337 $allow_null = isset($def->allow_null
);
341 $value = $this->parser
->parse($value, $type, $allow_null);
342 } catch (HTMLPurifier_VarParserException
$e) {
344 'Value for ' . $key . ' is of invalid type, should be ' .
345 HTMLPurifier_VarParser
::getTypeName($type),
350 if (is_string($value) && is_object($def)) {
351 // resolve value alias if defined
352 if (isset($def->aliases
[$value])) {
353 $value = $def->aliases
[$value];
355 // check to see if the value is allowed
356 if (isset($def->allowed
) && !isset($def->allowed
[$value])) {
358 'Value not supported, valid values are: ' .
359 $this->_listify($def->allowed
),
365 $this->plist
->set($key, $value);
367 // reset definitions if the directives they depend on changed
368 // this is a very costly process, so it's discouraged
370 if ($namespace == 'HTML' ||
$namespace == 'CSS' ||
$namespace == 'URI') {
371 $this->definitions
[$namespace] = null;
374 $this->serials
[$namespace] = false;
378 * Convenience function for error reporting
380 * @param array $lookup
384 private function _listify($lookup)
387 foreach ($lookup as $name => $b) $list[] = $name;
388 return implode(', ', $list);
392 * Retrieves object reference to the HTML definition.
394 * @param bool $raw Return a copy that has not been setup yet. Must be
395 * called before it's been setup, otherwise won't work.
396 * @param bool $optimized If true, this method may return null, to
397 * indicate that a cached version of the modified
398 * definition object is available and no further edits
399 * are necessary. Consider using
400 * maybeGetRawHTMLDefinition, which is more explicitly
405 public function getHTMLDefinition($raw = false, $optimized = false)
407 return $this->getDefinition('HTML', $raw, $optimized);
411 * Retrieves object reference to the CSS definition
413 * @param bool $raw Return a copy that has not been setup yet. Must be
414 * called before it's been setup, otherwise won't work.
415 * @param bool $optimized If true, this method may return null, to
416 * indicate that a cached version of the modified
417 * definition object is available and no further edits
418 * are necessary. Consider using
419 * maybeGetRawCSSDefinition, which is more explicitly
424 public function getCSSDefinition($raw = false, $optimized = false)
426 return $this->getDefinition('CSS', $raw, $optimized);
430 * Retrieves object reference to the URI definition
432 * @param bool $raw Return a copy that has not been setup yet. Must be
433 * called before it's been setup, otherwise won't work.
434 * @param bool $optimized If true, this method may return null, to
435 * indicate that a cached version of the modified
436 * definition object is available and no further edits
437 * are necessary. Consider using
438 * maybeGetRawURIDefinition, which is more explicitly
443 public function getURIDefinition($raw = false, $optimized = false)
445 return $this->getDefinition('URI', $raw, $optimized);
449 * Retrieves a definition
451 * @param string $type Type of definition: HTML, CSS, etc
452 * @param bool $raw Whether or not definition should be returned raw
453 * @param bool $optimized Only has an effect when $raw is true. Whether
454 * or not to return null if the result is already present in
455 * the cache. This is off by default for backwards
456 * compatibility reasons, but you need to do things this
457 * way in order to ensure that caching is done properly.
458 * Check out enduser-customize.html for more details.
459 * We probably won't ever change this default, as much as the
460 * maybe semantics is the "right thing to do."
462 * @throws HTMLPurifier_Exception
465 public function getDefinition($type, $raw = false, $optimized = false)
467 if ($optimized && !$raw) {
468 throw new HTMLPurifier_Exception("Cannot set optimized = true when raw = false");
470 if (!$this->finalized
) {
471 $this->autoFinalize();
473 // temporarily suspend locks, so we can handle recursive definition calls
476 $factory = HTMLPurifier_DefinitionCacheFactory
::instance();
477 $cache = $factory->create($type, $this);
482 // check if definition is in memory
483 if (!empty($this->definitions
[$type])) {
484 $def = $this->definitions
[$type];
485 // check if the definition is setup
490 if ($def->optimized
) {
491 $cache->add($def, $this);
496 // check if definition is in cache
497 $def = $cache->get($this);
499 // definition in cache, save to memory and return it
500 $this->definitions
[$type] = $def;
504 $def = $this->initDefinition($type);
510 $cache->add($def, $this);
516 // check preconditions
519 if (is_null($this->get($type . '.DefinitionID'))) {
520 // fatally error out if definition ID not set
521 throw new HTMLPurifier_Exception(
522 "Cannot retrieve raw version without specifying %$type.DefinitionID"
526 if (!empty($this->definitions
[$type])) {
527 $def = $this->definitions
[$type];
528 if ($def->setup
&& !$optimized) {
529 $extra = $this->chatty ?
530 " (try moving this code block earlier in your initialization)" :
532 throw new HTMLPurifier_Exception(
533 "Cannot retrieve raw definition after it has already been setup" .
537 if ($def->optimized
=== null) {
538 $extra = $this->chatty ?
" (try flushing your cache)" : "";
539 throw new HTMLPurifier_Exception(
540 "Optimization status of definition is unknown" . $extra
543 if ($def->optimized
!== $optimized) {
544 $msg = $optimized ?
"optimized" : "unoptimized";
545 $extra = $this->chatty ?
" (this backtrace is for the first inconsistent call, which was for a $msg raw definition)" : "";
546 throw new HTMLPurifier_Exception("Inconsistent use of optimized and unoptimized raw definition retrievals" . $extra);
549 // check if definition was in memory
552 // invariant: $optimized === true (checked above)
558 // if optimized, check if definition was in cache
559 // (because we do the memory check first, this formulation
560 // is prone to cache slamming, but I think
561 // guaranteeing that either /all/ of the raw
562 // setup code or /none/ of it is run is more important.)
564 // This code path only gets run once; once we put
565 // something in $definitions (which is guaranteed by the
566 // trailing code), we always short-circuit above.
567 $def = $cache->get($this);
569 // save the full definition for later, but don't
571 $this->definitions
[$type] = $def;
575 // check invariants for creation
577 if (!is_null($this->get($type . '.DefinitionID'))) {
579 $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
);
582 "Useless DefinitionID declaration",
589 $def = $this->initDefinition($type);
590 $def->optimized
= $optimized;
593 throw new HTMLPurifier_Exception("The impossible happened!");
597 * Initialise definition
599 * @param string $type What type of definition to create
601 * @return HTMLPurifier_CSSDefinition|HTMLPurifier_HTMLDefinition|HTMLPurifier_URIDefinition
602 * @throws HTMLPurifier_Exception
604 private function initDefinition($type)
606 // quick checks failed, let's create the object
607 if ($type == 'HTML') {
608 $def = new HTMLPurifier_HTMLDefinition();
609 } elseif ($type == 'CSS') {
610 $def = new HTMLPurifier_CSSDefinition();
611 } elseif ($type == 'URI') {
612 $def = new HTMLPurifier_URIDefinition();
614 throw new HTMLPurifier_Exception(
615 "Definition of $type type not supported"
618 $this->definitions
[$type] = $def;
622 public function maybeGetRawDefinition($name)
624 return $this->getDefinition($name, true, true);
627 public function maybeGetRawHTMLDefinition()
629 return $this->getDefinition('HTML', true, true);
632 public function maybeGetRawCSSDefinition()
634 return $this->getDefinition('CSS', true, true);
637 public function maybeGetRawURIDefinition()
639 return $this->getDefinition('URI', true, true);
643 * Loads configuration values from an array with the following structure:
644 * Namespace.Directive => Value
646 * @param array $config_array Configuration associative array
648 public function loadArray($config_array)
650 if ($this->isFinalized('Cannot load directives after finalization')) {
653 foreach ($config_array as $key => $value) {
654 $key = str_replace('_', '.', $key);
655 if (strpos($key, '.') !== false) {
656 $this->set($key, $value);
659 $namespace_values = $value;
660 foreach ($namespace_values as $directive => $value) {
661 $this->set($namespace .'.'. $directive, $value);
668 * Returns a list of array(namespace, directive) for all directives
669 * that are allowed in a web-form context as per an allowed
670 * namespaces/directives list.
672 * @param array $allowed List of allowed namespaces/directives
673 * @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
677 public static function getAllowedDirectivesForForm($allowed, $schema = null)
680 $schema = HTMLPurifier_ConfigSchema
::instance();
682 if ($allowed !== true) {
683 if (is_string($allowed)) {
684 $allowed = array($allowed);
686 $allowed_ns = array();
687 $allowed_directives = array();
688 $blacklisted_directives = array();
689 foreach ($allowed as $ns_or_directive) {
690 if (strpos($ns_or_directive, '.') !== false) {
692 if ($ns_or_directive[0] == '-') {
693 $blacklisted_directives[substr($ns_or_directive, 1)] = true;
695 $allowed_directives[$ns_or_directive] = true;
699 $allowed_ns[$ns_or_directive] = true;
704 foreach ($schema->info
as $key => $def) {
705 list($ns, $directive) = explode('.', $key, 2);
706 if ($allowed !== true) {
707 if (isset($blacklisted_directives["$ns.$directive"])) {
710 if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) {
714 if (isset($def->isAlias
)) {
717 if ($directive == 'DefinitionID' ||
$directive == 'DefinitionRev') {
720 $ret[] = array($ns, $directive);
726 * Loads configuration values from $_GET/$_POST that were posted
729 * @param array $array $_GET or $_POST array to import
730 * @param string|bool $index Index/name that the config variables are in
731 * @param array|bool $allowed List of allowed namespaces/directives
732 * @param bool $mq_fix Boolean whether or not to enable magic quotes fix
733 * @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
737 public static function loadArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null)
739 $ret = HTMLPurifier_Config
::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema);
740 $config = HTMLPurifier_Config
::create($ret, $schema);
745 * Merges in configuration values from $_GET/$_POST to object. NOT STATIC.
747 * @param array $array $_GET or $_POST array to import
748 * @param string|bool $index Index/name that the config variables are in
749 * @param array|bool $allowed List of allowed namespaces/directives
750 * @param bool $mq_fix Boolean whether or not to enable magic quotes fix
752 public function mergeArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true)
754 $ret = HTMLPurifier_Config
::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def
);
755 $this->loadArray($ret);
759 * Prepares an array from a form into something usable for the more
760 * strict parts of HTMLPurifier_Config
762 * @param array $array $_GET or $_POST array to import
763 * @param string|bool $index Index/name that the config variables are in
764 * @param array|bool $allowed List of allowed namespaces/directives
765 * @param bool $mq_fix Boolean whether or not to enable magic quotes fix
766 * @param HTMLPurifier_ConfigSchema $schema Schema to use, if not global copy
770 public static function prepareArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null)
772 if ($index !== false) {
773 $array = (isset($array[$index]) && is_array($array[$index])) ?
$array[$index] : array();
775 $mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc();
777 $allowed = HTMLPurifier_Config
::getAllowedDirectivesForForm($allowed, $schema);
779 foreach ($allowed as $key) {
780 list($ns, $directive) = $key;
781 $skey = "$ns.$directive";
782 if (!empty($array["Null_$skey"])) {
783 $ret[$ns][$directive] = null;
786 if (!isset($array[$skey])) {
789 $value = $mq ?
stripslashes($array[$skey]) : $array[$skey];
790 $ret[$ns][$directive] = $value;
796 * Loads configuration values from an ini file
798 * @param string $filename Name of ini file
800 public function loadIni($filename)
802 if ($this->isFinalized('Cannot load directives after finalization')) {
805 $array = parse_ini_file($filename, true);
806 $this->loadArray($array);
810 * Checks whether or not the configuration object is finalized.
812 * @param string|bool $error String error message, or false for no error
816 public function isFinalized($error = false)
818 if ($this->finalized
&& $error) {
819 $this->triggerError($error, E_USER_ERROR
);
821 return $this->finalized
;
825 * Finalizes configuration only if auto finalize is on and not
828 public function autoFinalize()
830 if ($this->autoFinalize
) {
833 $this->plist
->squash(true);
838 * Finalizes a configuration object, prohibiting further change
840 public function finalize()
842 $this->finalized
= true;
843 $this->parser
= null;
847 * Produces a nicely formatted error message by supplying the
848 * stack frame information OUTSIDE of HTMLPurifier_Config.
850 * @param string $msg An error message
851 * @param int $no An error number
853 protected function triggerError($msg, $no)
855 // determine previous stack frame
858 $trace = debug_backtrace();
859 // zip(tail(trace), trace) -- but PHP is not Haskell har har
860 for ($i = 0, $c = count($trace); $i < $c - 1; $i++
) {
861 // XXX this is not correct on some versions of HTML Purifier
862 if ($trace[$i +
1]['class'] === 'HTMLPurifier_Config') {
866 $extra = " invoked on line {$frame['line']} in file {$frame['file']}";
870 trigger_error($msg . $extra, $no);
874 * Returns a serialized form of the configuration object that can
879 public function serialize()
881 $this->getDefinition('HTML');
882 $this->getDefinition('CSS');
883 $this->getDefinition('URI');
884 return serialize($this);
889 // vim: et sw=4 sts=4