library/HTMLPurifier/Config.php

   1 <?php
   2
   3 /**
   4  * Configuration object that triggers customizable behavior.
   5  *
   6  * @warning This class is strongly defined: that means that the class
   7  *          will fail if an undefined directive is retrieved or set.
   8  *
   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.
  14  *
  15  * @todo Reconsider some of the public member variables
  16  */
  17 class HTMLPurifier_Config
  18 {
  19
  20     /**
  21      * HTML Purifier's version
  22      */
  23     public $version = '4.1.1';
  24
  25     /**
  26      * Bool indicator whether or not to automatically finalize
  27      * the object if a read operation is done
  28      */
  29     public $autoFinalize = true;
  30
  31     // protected member variables
  32
  33     /**
  34      * Namespace indexed array of serials for specific namespaces (see
  35      * getSerial() for more info).
  36      */
  37     protected $serials = array();
  38
  39     /**
  40      * Serial for entire configuration object
  41      */
  42     protected $serial;
  43
  44     /**
  45      * Parser for variables
  46      */
  47     protected $parser;
  48
  49     /**
  50      * Reference HTMLPurifier_ConfigSchema for value checking
  51      * @note This is public for introspective purposes. Please don't
  52      *       abuse!
  53      */
  54     public $def;
  55
  56     /**
  57      * Indexed array of definitions
  58      */
  59     protected $definitions;
  60
  61     /**
  62      * Bool indicator whether or not config is finalized
  63      */
  64     protected $finalized = false;
  65
  66     /**
  67      * Property list containing configuration directives.
  68      */
  69     protected $plist;
  70
  71     /**
  72      * Whether or not a set is taking place due to an
  73      * alias lookup.
  74      */
  75     private $aliasMode;
  76
  77     /**
  78      * Set to false if you do not want line and file numbers in errors
  79      * (useful when unit testing)
  80      */
  81     public $chatty = true;
  82
  83     /**
  84      * Current lock; only gets to this namespace are allowed.
  85      */
  86     private $lock;
  87
  88     /**
  89      * @param $definition HTMLPurifier_ConfigSchema that defines what directives
  90      *                    are allowed.
  91      */
  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();
  97     }
  98
  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
 107      */
 108     public static function create($config, $schema = null) {
 109         if ($config instanceof HTMLPurifier_Config) {
 110             // pass-through
 111             return $config;
 112         }
 113         if (!$schema) {
 114             $ret = HTMLPurifier_Config::createDefault();
 115         } else {
 116             $ret = new HTMLPurifier_Config($schema);
 117         }
 118         if (is_string($config)) $ret->loadIni($config);
 119         elseif (is_array($config)) $ret->loadArray($config);
 120         return $ret;
 121     }
 122
 123     /**
 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.
 128      */
 129     public static function inherit(HTMLPurifier_Config $config) {
 130         return new HTMLPurifier_Config($config->def, $config->plist);
 131     }
 132
 133     /**
 134      * Convenience constructor that creates a default configuration object.
 135      * @return Default HTMLPurifier_Config object.
 136      */
 137     public static function createDefault() {
 138         $definition = HTMLPurifier_ConfigSchema::instance();
 139         $config = new HTMLPurifier_Config($definition);
 140         return $config;
 141     }
 142
 143     /**
 144      * Retreives a value from the configuration.
 145      * @param $key String key
 146      */
 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";
 151         }
 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;
 158         }
 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;
 164         }
 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;
 170             }
 171         }
 172         return $this->plist->get($key);
 173     }
 174
 175     /**
 176      * Retreives an array of directives to values from a given namespace
 177      * @param $namespace String namespace
 178      */
 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;
 186         }
 187         return $full[$namespace];
 188     }
 189
 190     /**
 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
 196      */
 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));
 202         }
 203         return $this->serials[$namespace];
 204     }
 205
 206     /**
 207      * Returns a md5 signature for the entire configuration object
 208      * that uniquely identifies that particular configuration
 209      */
 210     public function getSerial() {
 211         if (empty($this->serial)) {
 212             $this->serial = md5(serialize($this->getAll()));
 213         }
 214         return $this->serial;
 215     }
 216
 217     /**
 218      * Retrieves all directives, organized by namespace
 219      * @warning This is a pretty inefficient function, avoid if you can
 220      */
 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;
 227         }
 228         return $ret;
 229     }
 230
 231     /**
 232      * Sets a value to configuration.
 233      * @param $key String key
 234      * @param $value Mixed value
 235      */
 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);
 245         }
 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;
 251         }
 252         $def = $this->def->info[$key];
 253
 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;
 259             }
 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;
 265         }
 266
 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);
 276         }
 277
 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;
 283         }
 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];
 288             }
 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;
 294             }
 295         }
 296         $this->plist->set($key, $value);
 297
 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;
 303         }
 304
 305         $this->serials[$namespace] = false;
 306     }
 307
 308     /**
 309      * Convenience function for error reporting
 310      */
 311     private function _listify($lookup) {
 312         $list = array();
 313         foreach ($lookup as $name => $b) $list[] = $name;
 314         return implode(', ', $list);
 315     }
 316
 317     /**
 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.
 321      */
 322     public function getHTMLDefinition($raw = false) {
 323         return $this->getDefinition('HTML', $raw);
 324     }
 325
 326     /**
 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.
 330      */
 331     public function getCSSDefinition($raw = false) {
 332         return $this->getDefinition('CSS', $raw);
 333     }
 334
 335     /**
 336      * Retrieves a definition
 337      * @param $type Type of definition: HTML, CSS, etc
 338      * @param $raw  Whether or not definition should be returned raw
 339      */
 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);
 354                 }
 355                 return $this->definitions[$type];
 356             }
 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];
 362             }
 363         } elseif (
 364             !empty($this->definitions[$type]) &&
 365             !$this->definitions[$type]->setup
 366         ) {
 367             // raw requested, raw in memory, quick return
 368             return $this->definitions[$type];
 369         }
 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");
 379         }
 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");
 385             }
 386             return $this->definitions[$type];
 387         }
 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];
 395     }
 396
 397     /**
 398      * Loads configuration values from an array with the following structure:
 399      * Namespace.Directive => Value
 400      * @param $config_array Configuration associative array
 401      */
 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);
 413                 }
 414             }
 415         }
 416     }
 417
 418     /**
 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
 423      */
 424     public static function getAllowedDirectivesForForm($allowed, $schema = null) {
 425         if (!$schema) {
 426             $schema = HTMLPurifier_ConfigSchema::instance();
 427         }
 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;
 440                      }
 441                  } else {
 442                      // namespace
 443                      $allowed_ns[$ns_or_directive] = true;
 444                  }
 445              }
 446         }
 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;
 453             }
 454             if (isset($def->isAlias)) continue;
 455             if ($directive == 'DefinitionID' || $directive == 'DefinitionRev') continue;
 456             $ret[] = array($ns, $directive);
 457         }
 458         return $ret;
 459     }
 460
 461     /**
 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
 469      */
 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;
 474     }
 475
 476     /**
 477      * Merges in configuration values from $_GET/$_POST to object. NOT STATIC.
 478      * @note Same parameters as loadArrayFromForm
 479      */
 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);
 483     }
 484
 485     /**
 486      * Prepares an array from a form into something usable for the more
 487      * strict parts of HTMLPurifier_Config
 488      */
 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();
 492
 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;
 501             }
 502             if (!isset($array[$skey])) continue;
 503             $value = $mq ? stripslashes($array[$skey]) : $array[$skey];
 504             $ret[$ns][$directive] = $value;
 505         }
 506         return $ret;
 507     }
 508
 509     /**
 510      * Loads configuration values from an ini file
 511      * @param $filename Name of ini file
 512      */
 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);
 517     }
 518
 519     /**
 520      * Checks whether or not the configuration object is finalized.
 521      * @param $error String error message, or false for no error
 522      */
 523     public function isFinalized($error = false) {
 524         if ($this->finalized && $error) {
 525             $this->triggerError($error, E_USER_ERROR);
 526         }
 527         return $this->finalized;
 528     }
 529
 530     /**
 531      * Finalizes configuration only if auto finalize is on and not
 532      * already finalized
 533      */
 534     public function autoFinalize() {
 535         if ($this->autoFinalize) {
 536             $this->finalize();
 537         } else {
 538             $this->plist->squash(true);
 539         }
 540     }
 541
 542     /**
 543      * Finalizes a configuration object, prohibiting further change
 544      */
 545     public function finalize() {
 546         $this->finalized = true;
 547         unset($this->parser);
 548     }
 549
 550     /**
 551      * Produces a nicely formatted error message by supplying the
 552      * stack frame information from two levels up and OUTSIDE of
 553      * HTMLPurifier_Config.
 554      */
 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 = '';
 563         }
 564         trigger_error($msg . $extra, $no);
 565     }
 566
 567     /**
 568      * Returns a serialized form of the configuration object that can
 569      * be reconstituted.
 570      */
 571     public function serialize() {
 572         $this->getDefinition('HTML');
 573         $this->getDefinition('CSS');
 574         $this->getDefinition('URI');
 575         return serialize($this);
 576     }
 577
 578 }
 579
 580 // vim: et sw=4 sts=4