Release 4.2.0.
[htmlpurifier.git] / library / HTMLPurifier / Config.php
blob54d4085363d78cc7e3410155e2f0f457d280f8e8
1 <?php
3 /**
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
20 /**
21 * HTML Purifier's version
23 public $version = '4.2.0';
25 /**
26 * 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
33 /**
34 * Namespace indexed array of serials for specific namespaces (see
35 * getSerial() for more info).
37 protected $serials = array();
39 /**
40 * Serial for entire configuration object
42 protected $serial;
44 /**
45 * Parser for variables
47 protected $parser;
49 /**
50 * Reference HTMLPurifier_ConfigSchema for value checking
51 * @note This is public for introspective purposes. Please don't
52 * abuse!
54 public $def;
56 /**
57 * Indexed array of definitions
59 protected $definitions;
61 /**
62 * Bool indicator whether or not config is finalized
64 protected $finalized = false;
66 /**
67 * Property list containing configuration directives.
69 protected $plist;
71 /**
72 * Whether or not a set is taking place due to an
73 * alias lookup.
75 private $aliasMode;
77 /**
78 * Set to false if you do not want line and file numbers in errors
79 * (useful when unit testing)
81 public $chatty = true;
83 /**
84 * Current lock; only gets to this namespace are allowed.
86 private $lock;
88 /**
89 * @param $definition HTMLPurifier_ConfigSchema that defines what directives
90 * are allowed.
92 public function __construct($definition, $parent = null) {
93 $parent = $parent ? $parent : $definition->defaultPlist;
94 $this->plist = new HTMLPurifier_PropertyList($parent);
95 $this->def = $definition; // keep a copy around for checking
96 $this->parser = new HTMLPurifier_VarParser_Flexible();
99 /**
100 * Convenience constructor that creates a config object based on a mixed var
101 * @param mixed $config Variable that defines the state of the config
102 * object. Can be: a HTMLPurifier_Config() object,
103 * an array of directives based on loadArray(),
104 * or a string filename of an ini file.
105 * @param HTMLPurifier_ConfigSchema Schema object
106 * @return Configured HTMLPurifier_Config object
108 public static function create($config, $schema = null) {
109 if ($config instanceof HTMLPurifier_Config) {
110 // pass-through
111 return $config;
113 if (!$schema) {
114 $ret = HTMLPurifier_Config::createDefault();
115 } else {
116 $ret = new HTMLPurifier_Config($schema);
118 if (is_string($config)) $ret->loadIni($config);
119 elseif (is_array($config)) $ret->loadArray($config);
120 return $ret;
124 * Creates a new config object that inherits from a previous one.
125 * @param HTMLPurifier_Config $config Configuration object to inherit
126 * from.
127 * @return HTMLPurifier_Config object with $config as its parent.
129 public static function inherit(HTMLPurifier_Config $config) {
130 return new HTMLPurifier_Config($config->def, $config->plist);
134 * Convenience constructor that creates a default configuration object.
135 * @return Default HTMLPurifier_Config object.
137 public static function createDefault() {
138 $definition = HTMLPurifier_ConfigSchema::instance();
139 $config = new HTMLPurifier_Config($definition);
140 return $config;
144 * Retreives a value from the configuration.
145 * @param $key String key
147 public function get($key, $a = null) {
148 if ($a !== null) {
149 $this->triggerError("Using deprecated API: use \$config->get('$key.$a') instead", E_USER_WARNING);
150 $key = "$key.$a";
152 if (!$this->finalized) $this->autoFinalize();
153 if (!isset($this->def->info[$key])) {
154 // can't add % due to SimpleTest bug
155 $this->triggerError('Cannot retrieve value of undefined directive ' . htmlspecialchars($key),
156 E_USER_WARNING);
157 return;
159 if (isset($this->def->info[$key]->isAlias)) {
160 $d = $this->def->info[$key];
161 $this->triggerError('Cannot get value from aliased directive, use real name ' . $d->key,
162 E_USER_ERROR);
163 return;
165 if ($this->lock) {
166 list($ns) = explode('.', $key);
167 if ($ns !== $this->lock) {
168 $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);
169 return;
172 return $this->plist->get($key);
176 * Retreives an array of directives to values from a given namespace
177 * @param $namespace String namespace
179 public function getBatch($namespace) {
180 if (!$this->finalized) $this->autoFinalize();
181 $full = $this->getAll();
182 if (!isset($full[$namespace])) {
183 $this->triggerError('Cannot retrieve undefined namespace ' . htmlspecialchars($namespace),
184 E_USER_WARNING);
185 return;
187 return $full[$namespace];
191 * Returns a md5 signature of a segment of the configuration object
192 * that uniquely identifies that particular configuration
193 * @note Revision is handled specially and is removed from the batch
194 * before processing!
195 * @param $namespace Namespace to get serial for
197 public function getBatchSerial($namespace) {
198 if (empty($this->serials[$namespace])) {
199 $batch = $this->getBatch($namespace);
200 unset($batch['DefinitionRev']);
201 $this->serials[$namespace] = md5(serialize($batch));
203 return $this->serials[$namespace];
207 * Returns a md5 signature for the entire configuration object
208 * that uniquely identifies that particular configuration
210 public function getSerial() {
211 if (empty($this->serial)) {
212 $this->serial = md5(serialize($this->getAll()));
214 return $this->serial;
218 * Retrieves all directives, organized by namespace
219 * @warning This is a pretty inefficient function, avoid if you can
221 public function getAll() {
222 if (!$this->finalized) $this->autoFinalize();
223 $ret = array();
224 foreach ($this->plist->squash() as $name => $value) {
225 list($ns, $key) = explode('.', $name, 2);
226 $ret[$ns][$key] = $value;
228 return $ret;
232 * Sets a value to configuration.
233 * @param $key String key
234 * @param $value Mixed value
236 public function set($key, $value, $a = null) {
237 if (strpos($key, '.') === false) {
238 $namespace = $key;
239 $directive = $value;
240 $value = $a;
241 $key = "$key.$directive";
242 $this->triggerError("Using deprecated API: use \$config->set('$key', ...) instead", E_USER_NOTICE);
243 } else {
244 list($namespace) = explode('.', $key);
246 if ($this->isFinalized('Cannot set directive after finalization')) return;
247 if (!isset($this->def->info[$key])) {
248 $this->triggerError('Cannot set undefined directive ' . htmlspecialchars($key) . ' to value',
249 E_USER_WARNING);
250 return;
252 $def = $this->def->info[$key];
254 if (isset($def->isAlias)) {
255 if ($this->aliasMode) {
256 $this->triggerError('Double-aliases not allowed, please fix '.
257 'ConfigSchema bug with' . $key, E_USER_ERROR);
258 return;
260 $this->aliasMode = true;
261 $this->set($def->key, $value);
262 $this->aliasMode = false;
263 $this->triggerError("$key is an alias, preferred directive name is {$def->key}", E_USER_NOTICE);
264 return;
267 // Raw type might be negative when using the fully optimized form
268 // of stdclass, which indicates allow_null == true
269 $rtype = is_int($def) ? $def : $def->type;
270 if ($rtype < 0) {
271 $type = -$rtype;
272 $allow_null = true;
273 } else {
274 $type = $rtype;
275 $allow_null = isset($def->allow_null);
278 try {
279 $value = $this->parser->parse($value, $type, $allow_null);
280 } catch (HTMLPurifier_VarParserException $e) {
281 $this->triggerError('Value for ' . $key . ' is of invalid type, should be ' . HTMLPurifier_VarParser::getTypeName($type), E_USER_WARNING);
282 return;
284 if (is_string($value) && is_object($def)) {
285 // resolve value alias if defined
286 if (isset($def->aliases[$value])) {
287 $value = $def->aliases[$value];
289 // check to see if the value is allowed
290 if (isset($def->allowed) && !isset($def->allowed[$value])) {
291 $this->triggerError('Value not supported, valid values are: ' .
292 $this->_listify($def->allowed), E_USER_WARNING);
293 return;
296 $this->plist->set($key, $value);
298 // reset definitions if the directives they depend on changed
299 // this is a very costly process, so it's discouraged
300 // with finalization
301 if ($namespace == 'HTML' || $namespace == 'CSS' || $namespace == 'URI') {
302 $this->definitions[$namespace] = null;
305 $this->serials[$namespace] = false;
309 * Convenience function for error reporting
311 private function _listify($lookup) {
312 $list = array();
313 foreach ($lookup as $name => $b) $list[] = $name;
314 return implode(', ', $list);
318 * Retrieves object reference to the HTML definition.
319 * @param $raw Return a copy that has not been setup yet. Must be
320 * called before it's been setup, otherwise won't work.
322 public function getHTMLDefinition($raw = false) {
323 return $this->getDefinition('HTML', $raw);
327 * Retrieves object reference to the CSS definition
328 * @param $raw Return a copy that has not been setup yet. Must be
329 * called before it's been setup, otherwise won't work.
331 public function getCSSDefinition($raw = false) {
332 return $this->getDefinition('CSS', $raw);
336 * Retrieves a definition
337 * @param $type Type of definition: HTML, CSS, etc
338 * @param $raw Whether or not definition should be returned raw
340 public function getDefinition($type, $raw = false) {
341 if (!$this->finalized) $this->autoFinalize();
342 // temporarily suspend locks, so we can handle recursive definition calls
343 $lock = $this->lock;
344 $this->lock = null;
345 $factory = HTMLPurifier_DefinitionCacheFactory::instance();
346 $cache = $factory->create($type, $this);
347 $this->lock = $lock;
348 if (!$raw) {
349 // see if we can quickly supply a definition
350 if (!empty($this->definitions[$type])) {
351 if (!$this->definitions[$type]->setup) {
352 $this->definitions[$type]->setup($this);
353 $cache->set($this->definitions[$type], $this);
355 return $this->definitions[$type];
357 // memory check missed, try cache
358 $this->definitions[$type] = $cache->get($this);
359 if ($this->definitions[$type]) {
360 // definition in cache, return it
361 return $this->definitions[$type];
363 } elseif (
364 !empty($this->definitions[$type]) &&
365 !$this->definitions[$type]->setup
367 // raw requested, raw in memory, quick return
368 return $this->definitions[$type];
370 // quick checks failed, let's create the object
371 if ($type == 'HTML') {
372 $this->definitions[$type] = new HTMLPurifier_HTMLDefinition();
373 } elseif ($type == 'CSS') {
374 $this->definitions[$type] = new HTMLPurifier_CSSDefinition();
375 } elseif ($type == 'URI') {
376 $this->definitions[$type] = new HTMLPurifier_URIDefinition();
377 } else {
378 throw new HTMLPurifier_Exception("Definition of $type type not supported");
380 // quick abort if raw
381 if ($raw) {
382 if (is_null($this->get($type . '.DefinitionID'))) {
383 // fatally error out if definition ID not set
384 throw new HTMLPurifier_Exception("Cannot retrieve raw version without specifying %$type.DefinitionID");
386 return $this->definitions[$type];
388 // set it up
389 $this->lock = $type;
390 $this->definitions[$type]->setup($this);
391 $this->lock = null;
392 // save in cache
393 $cache->set($this->definitions[$type], $this);
394 return $this->definitions[$type];
398 * Loads configuration values from an array with the following structure:
399 * Namespace.Directive => Value
400 * @param $config_array Configuration associative array
402 public function loadArray($config_array) {
403 if ($this->isFinalized('Cannot load directives after finalization')) return;
404 foreach ($config_array as $key => $value) {
405 $key = str_replace('_', '.', $key);
406 if (strpos($key, '.') !== false) {
407 $this->set($key, $value);
408 } else {
409 $namespace = $key;
410 $namespace_values = $value;
411 foreach ($namespace_values as $directive => $value) {
412 $this->set($namespace .'.'. $directive, $value);
419 * Returns a list of array(namespace, directive) for all directives
420 * that are allowed in a web-form context as per an allowed
421 * namespaces/directives list.
422 * @param $allowed List of allowed namespaces/directives
424 public static function getAllowedDirectivesForForm($allowed, $schema = null) {
425 if (!$schema) {
426 $schema = HTMLPurifier_ConfigSchema::instance();
428 if ($allowed !== true) {
429 if (is_string($allowed)) $allowed = array($allowed);
430 $allowed_ns = array();
431 $allowed_directives = array();
432 $blacklisted_directives = array();
433 foreach ($allowed as $ns_or_directive) {
434 if (strpos($ns_or_directive, '.') !== false) {
435 // directive
436 if ($ns_or_directive[0] == '-') {
437 $blacklisted_directives[substr($ns_or_directive, 1)] = true;
438 } else {
439 $allowed_directives[$ns_or_directive] = true;
441 } else {
442 // namespace
443 $allowed_ns[$ns_or_directive] = true;
447 $ret = array();
448 foreach ($schema->info as $key => $def) {
449 list($ns, $directive) = explode('.', $key, 2);
450 if ($allowed !== true) {
451 if (isset($blacklisted_directives["$ns.$directive"])) continue;
452 if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) continue;
454 if (isset($def->isAlias)) continue;
455 if ($directive == 'DefinitionID' || $directive == 'DefinitionRev') continue;
456 $ret[] = array($ns, $directive);
458 return $ret;
462 * Loads configuration values from $_GET/$_POST that were posted
463 * via ConfigForm
464 * @param $array $_GET or $_POST array to import
465 * @param $index Index/name that the config variables are in
466 * @param $allowed List of allowed namespaces/directives
467 * @param $mq_fix Boolean whether or not to enable magic quotes fix
468 * @param $schema Instance of HTMLPurifier_ConfigSchema to use, if not global copy
470 public static function loadArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) {
471 $ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema);
472 $config = HTMLPurifier_Config::create($ret, $schema);
473 return $config;
477 * Merges in configuration values from $_GET/$_POST to object. NOT STATIC.
478 * @note Same parameters as loadArrayFromForm
480 public function mergeArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true) {
481 $ret = HTMLPurifier_Config::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def);
482 $this->loadArray($ret);
486 * Prepares an array from a form into something usable for the more
487 * strict parts of HTMLPurifier_Config
489 public static function prepareArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) {
490 if ($index !== false) $array = (isset($array[$index]) && is_array($array[$index])) ? $array[$index] : array();
491 $mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc();
493 $allowed = HTMLPurifier_Config::getAllowedDirectivesForForm($allowed, $schema);
494 $ret = array();
495 foreach ($allowed as $key) {
496 list($ns, $directive) = $key;
497 $skey = "$ns.$directive";
498 if (!empty($array["Null_$skey"])) {
499 $ret[$ns][$directive] = null;
500 continue;
502 if (!isset($array[$skey])) continue;
503 $value = $mq ? stripslashes($array[$skey]) : $array[$skey];
504 $ret[$ns][$directive] = $value;
506 return $ret;
510 * Loads configuration values from an ini file
511 * @param $filename Name of ini file
513 public function loadIni($filename) {
514 if ($this->isFinalized('Cannot load directives after finalization')) return;
515 $array = parse_ini_file($filename, true);
516 $this->loadArray($array);
520 * Checks whether or not the configuration object is finalized.
521 * @param $error String error message, or false for no error
523 public function isFinalized($error = false) {
524 if ($this->finalized && $error) {
525 $this->triggerError($error, E_USER_ERROR);
527 return $this->finalized;
531 * Finalizes configuration only if auto finalize is on and not
532 * already finalized
534 public function autoFinalize() {
535 if ($this->autoFinalize) {
536 $this->finalize();
537 } else {
538 $this->plist->squash(true);
543 * Finalizes a configuration object, prohibiting further change
545 public function finalize() {
546 $this->finalized = true;
547 unset($this->parser);
551 * Produces a nicely formatted error message by supplying the
552 * stack frame information from two levels up and OUTSIDE of
553 * HTMLPurifier_Config.
555 protected function triggerError($msg, $no) {
556 // determine previous stack frame
557 $backtrace = debug_backtrace();
558 if ($this->chatty && isset($backtrace[1])) {
559 $frame = $backtrace[1];
560 $extra = " on line {$frame['line']} in file {$frame['file']}";
561 } else {
562 $extra = '';
564 trigger_error($msg . $extra, $no);
568 * Returns a serialized form of the configuration object that can
569 * be reconstituted.
571 public function serialize() {
572 $this->getDefinition('HTML');
573 $this->getDefinition('CSS');
574 $this->getDefinition('URI');
575 return serialize($this);
580 // vim: et sw=4 sts=4