library/HTMLPurifier/ConfigSchema.php

   1 <?php
   2
   3 if (!defined('HTMLPURIFIER_SCHEMA_STRICT')) define('HTMLPURIFIER_SCHEMA_STRICT', false);
   4
   5 /**
   6  * Configuration definition, defines directives and their defaults.
   7  */
   8 class HTMLPurifier_ConfigSchema {
   9
  10     /**
  11      * Defaults of the directives and namespaces.
  12      * @note This shares the exact same structure as HTMLPurifier_Config::$conf
  13      */
  14     public $defaults = array();
  15
  16     /**
  17      * Definition of the directives.
  18      */
  19     public $info = array();
  20
  21     /**
  22      * Definition of namespaces.
  23      */
  24     public $info_namespace = array();
  25
  26     /**
  27      * Application-wide singleton
  28      */
  29     static protected $singleton;
  30
  31     /**
  32      * Variable parser.
  33      */
  34     protected $parser;
  35
  36     /**
  37      * Lookup table of allowed types.
  38      */
  39     public $types = array(
  40         'string'    => 'String',
  41         'istring'   => 'Case-insensitive string',
  42         'text'      => 'Text',
  43         'itext'      => 'Case-insensitive text',
  44         'int'       => 'Integer',
  45         'float'     => 'Float',
  46         'bool'      => 'Boolean',
  47         'lookup'    => 'Lookup array',
  48         'list'      => 'Array list',
  49         'hash'      => 'Associative array',
  50         'mixed'     => 'Mixed'
  51     );
  52
  53     public function __construct() {
  54         $this->parser = new HTMLPurifier_VarParser_Flexible();
  55     }
  56
  57     /**
  58      * Unserializes the default ConfigSchema.
  59      */
  60     public static function makeFromSerial() {
  61         return unserialize(file_get_contents(HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema.ser'));
  62     }
  63
  64     /**
  65      * Retrieves an instance of the application-wide configuration definition.
  66      */
  67     public static function &instance($prototype = null) {
  68         if ($prototype !== null) {
  69             HTMLPurifier_ConfigSchema::$singleton = $prototype;
  70         } elseif (HTMLPurifier_ConfigSchema::$singleton === null || $prototype === true) {
  71             HTMLPurifier_ConfigSchema::$singleton = HTMLPurifier_ConfigSchema::makeFromSerial();
  72         }
  73         return HTMLPurifier_ConfigSchema::$singleton;
  74     }
  75
  76     /**
  77      * Throws an E_USER_NOTICE stating that a method is deprecated.
  78      */
  79     private static function deprecated($method) {
  80         trigger_error("Static HTMLPurifier_ConfigSchema::$method deprecated, use add*() method instead", E_USER_NOTICE);
  81     }
  82
  83     /** @see HTMLPurifier_ConfigSchema->set() */
  84     public static function define($namespace, $name, $default, $type, $description) {
  85         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
  86         $def =& HTMLPurifier_ConfigSchema::instance();
  87         $def->add($namespace, $name, $default, $type, $description);
  88     }
  89
  90     /**
  91      * Defines a directive for configuration
  92      * @warning Will fail of directive's namespace is defined
  93      * @param $namespace Namespace the directive is in
  94      * @param $name Key of directive
  95      * @param $default Default value of directive
  96      * @param $type Allowed type of the directive. See
  97      *      HTMLPurifier_DirectiveDef::$type for allowed values
  98      * @param $description Description of directive for documentation
  99      */
 100     public function add($namespace, $name, $default, $type, $description) {
 101         // basic sanity checks
 102         if (HTMLPURIFIER_SCHEMA_STRICT) {
 103             if (!isset($this->info[$namespace])) {
 104                 trigger_error('Cannot define directive for undefined namespace',
 105                     E_USER_ERROR);
 106                 return;
 107             }
 108             if (!ctype_alnum($name)) {
 109                 trigger_error('Directive name must be alphanumeric',
 110                     E_USER_ERROR);
 111                 return;
 112             }
 113             if (empty($description)) {
 114                 trigger_error('Description must be non-empty',
 115                     E_USER_ERROR);
 116                 return;
 117             }
 118         }
 119
 120         if (isset($this->info[$namespace][$name])) {
 121             // already defined
 122             trigger_error('Cannot redefine directive');
 123             return;
 124         } else {
 125             // needs defining
 126
 127             // process modifiers (OPTIMIZE!)
 128             $type_values = explode('/', $type, 2);
 129             $type = $type_values[0];
 130             $modifier = isset($type_values[1]) ? $type_values[1] : false;
 131             $allow_null = ($modifier === 'null');
 132
 133             if (HTMLPURIFIER_SCHEMA_STRICT) {
 134                 if (!isset($this->types[$type])) {
 135                     trigger_error('Invalid type for configuration directive',
 136                         E_USER_ERROR);
 137                     return;
 138                 }
 139                 try {
 140                     $default = $this->parser->parse($default, $type, $allow_null);
 141                 } catch (HTMLPurifier_VarParserException $e) {
 142                     trigger_error('Default value does not match directive type',
 143                         E_USER_ERROR);
 144                     return;
 145                 }
 146             }
 147
 148             $this->info[$namespace][$name] =
 149                 new HTMLPurifier_ConfigDef_Directive();
 150             $this->info[$namespace][$name]->type = $type;
 151             $this->info[$namespace][$name]->allow_null = $allow_null;
 152             $this->defaults[$namespace][$name]   = $default;
 153         }
 154         if (!HTMLPURIFIER_SCHEMA_STRICT) return;
 155         $this->info[$namespace][$name]->description = $description;
 156     }
 157
 158     /** @see HTMLPurifier_ConfigSchema->addNamespace() */
 159     public static function defineNamespace($namespace, $description) {
 160         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 161         $def =& HTMLPurifier_ConfigSchema::instance();
 162         $def->addNamespace($namespace, $description);
 163     }
 164
 165     /**
 166      * Defines a namespace for directives to be put into.
 167      * @param $namespace Namespace's name
 168      * @param $description Description of the namespace
 169      */
 170     public function addNamespace($namespace, $description) {
 171         $this->info[$namespace] = array();
 172         $this->info_namespace[$namespace] = new HTMLPurifier_ConfigDef_Namespace();
 173         $this->info_namespace[$namespace]->description = $description;
 174         $this->defaults[$namespace] = array();
 175     }
 176
 177     /** @see HTMLPurifier_ConfigSchema->addValueAliases() */
 178     public static function defineValueAliases($namespace, $name, $aliases) {
 179         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 180         $def =& HTMLPurifier_ConfigSchema::instance();
 181         $def->addValueAliases($namespace, $name, $aliases);
 182     }
 183
 184     /**
 185      * Defines a directive value alias.
 186      *
 187      * Directive value aliases are convenient for developers because it lets
 188      * them set a directive to several values and get the same result.
 189      * @param $namespace Directive's namespace
 190      * @param $name Name of Directive
 191      * @param $alias Name of aliased value
 192      * @param $real Value aliased value will be converted into
 193      */
 194     public function addValueAliases($namespace, $name, $aliases) {
 195         if (HTMLPURIFIER_SCHEMA_STRICT && !isset($this->info[$namespace][$name])) {
 196             trigger_error('Cannot set value alias for non-existant directive',
 197                 E_USER_ERROR);
 198             return;
 199         }
 200         foreach ($aliases as $alias => $real) {
 201             if (HTMLPURIFIER_SCHEMA_STRICT) {
 202                 if (!$this->info[$namespace][$name] !== true &&
 203                     !isset($this->info[$namespace][$name]->allowed[$real])
 204                 ) {
 205                     trigger_error('Cannot define alias to value that is not allowed',
 206                         E_USER_ERROR);
 207                     return;
 208                 }
 209                 if (isset($this->info[$namespace][$name]->allowed[$alias])) {
 210                     trigger_error('Cannot define alias over allowed value',
 211                         E_USER_ERROR);
 212                     return;
 213                 }
 214             }
 215             $this->info[$namespace][$name]->aliases[$alias] = $real;
 216         }
 217     }
 218
 219     /** @see HTMLPurifier_ConfigSchema->addAllowedValues() */
 220     public static function defineAllowedValues($namespace, $name, $allowed_values) {
 221         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 222         $def =& HTMLPurifier_ConfigSchema::instance();
 223         $def->addAllowedValues($namespace, $name, $allowed_values);
 224     }
 225
 226     /**
 227      * Defines a set of allowed values for a directive.
 228      * @param $namespace Namespace of directive
 229      * @param $name Name of directive
 230      * @param $allowed_values Arraylist of allowed values
 231      */
 232     public function addAllowedValues($namespace, $name, $allowed_values) {
 233         if (HTMLPURIFIER_SCHEMA_STRICT && !isset($this->info[$namespace][$name])) {
 234             trigger_error('Cannot define allowed values for undefined directive',
 235                 E_USER_ERROR);
 236             return;
 237         }
 238         $directive =& $this->info[$namespace][$name];
 239         $type = $directive->type;
 240         if (HTMLPURIFIER_SCHEMA_STRICT && $type != 'string' && $type != 'istring') {
 241             trigger_error('Cannot define allowed values for directive whose type is not string',
 242                 E_USER_ERROR);
 243             return;
 244         }
 245         if ($directive->allowed === true) {
 246             $directive->allowed = array();
 247         }
 248         foreach ($allowed_values as $value) {
 249             $directive->allowed[$value] = true;
 250         }
 251         if (
 252             HTMLPURIFIER_SCHEMA_STRICT &&
 253             $this->defaults[$namespace][$name] !== null &&
 254             !isset($directive->allowed[$this->defaults[$namespace][$name]])
 255         ) {
 256             trigger_error('Default value must be in allowed range of variables',
 257                 E_USER_ERROR);
 258             $directive->allowed = true; // undo undo!
 259             return;
 260         }
 261     }
 262
 263     /** @see HTMLPurifier_ConfigSchema->addAlias() */
 264     public static function defineAlias($namespace, $name, $new_namespace, $new_name) {
 265         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 266         $def =& HTMLPurifier_ConfigSchema::instance();
 267         $def->addAlias($namespace, $name, $new_namespace, $new_name);
 268     }
 269
 270     /**
 271      * Defines a directive alias for backwards compatibility
 272      * @param $namespace
 273      * @param $name Directive that will be aliased
 274      * @param $new_namespace
 275      * @param $new_name Directive that the alias will be to
 276      */
 277     public function addAlias($namespace, $name, $new_namespace, $new_name) {
 278         if (HTMLPURIFIER_SCHEMA_STRICT) {
 279             if (!isset($this->info[$namespace])) {
 280                 trigger_error('Cannot define directive alias in undefined namespace',
 281                     E_USER_ERROR);
 282                 return;
 283             }
 284             if (!ctype_alnum($name)) {
 285                 trigger_error('Directive name must be alphanumeric',
 286                     E_USER_ERROR);
 287                 return;
 288             }
 289             if (isset($this->info[$namespace][$name])) {
 290                 trigger_error('Cannot define alias over directive',
 291                     E_USER_ERROR);
 292                 return;
 293             }
 294             if (!isset($this->info[$new_namespace][$new_name])) {
 295                 trigger_error('Cannot define alias to undefined directive',
 296                     E_USER_ERROR);
 297                 return;
 298             }
 299             if ($this->info[$new_namespace][$new_name]->class == 'alias') {
 300                 trigger_error('Cannot define alias to alias',
 301                     E_USER_ERROR);
 302                 return;
 303             }
 304         }
 305         $this->info[$namespace][$name] =
 306             new HTMLPurifier_ConfigDef_DirectiveAlias(
 307                 $new_namespace, $new_name);
 308         $this->info[$new_namespace][$new_name]->directiveAliases[] = "$namespace.$name";
 309     }
 310
 311     /**
 312      * Takes an absolute path and munges it into a more manageable relative path
 313      * @todo Consider making protected
 314      * @param $filename Filename to check
 315      * @return string munged filename
 316      */
 317     public function mungeFilename($filename) {
 318         if (!HTMLPURIFIER_SCHEMA_STRICT) return $filename;
 319         $offset = strrpos($filename, 'HTMLPurifier');
 320         $filename = substr($filename, $offset);
 321         $filename = str_replace('\\', '/', $filename);
 322         return $filename;
 323     }
 324
 325     /**
 326      * Checks if var is an HTMLPurifier_Error object
 327      * @todo Consider making protected
 328      */
 329     public function isError($var) {
 330         if (!is_object($var)) return false;
 331         if (!($var instanceof HTMLPurifier_Error)) return false;
 332         return true;
 333     }
 334
 335     /** @deprecated, use HTMLPurifier_VarParser->parse() */
 336     public function validate($a, $b, $c = false) {
 337         trigger_error("HTMLPurifier_ConfigSchema->validate deprecated, use HTMLPurifier_VarParser->parse instead", E_USER_NOTICE);
 338         return $this->parser->parse($a, $b, $c);
 339     }
 340
 341 }
 342
 343