library/HTMLPurifier/ConfigSchema.php

   1 <?php
   2
   3 /**
   4  * Configuration definition, defines directives and their defaults.
   5  */
   6 class HTMLPurifier_ConfigSchema {
   7
   8     /**
   9      * Defaults of the directives and namespaces.
  10      * @note This shares the exact same structure as HTMLPurifier_Config::$conf
  11      */
  12     public $defaults = array();
  13
  14     /**
  15      * The default property list. Do not edit this property list.
  16      */
  17     public $defaultPlist;
  18
  19     /**
  20      * Definition of the directives. The structure of this is:
  21      *
  22      *  array(
  23      *      'Namespace' => array(
  24      *          'Directive' => new stdclass(),
  25      *      )
  26      *  )
  27      *
  28      * The stdclass may have the following properties:
  29      *
  30      *  - If isAlias isn't set:
  31      *      - type: Integer type of directive, see HTMLPurifier_VarParser for definitions
  32      *      - allow_null: If set, this directive allows null values
  33      *      - aliases: If set, an associative array of value aliases to real values
  34      *      - allowed: If set, a lookup array of allowed (string) values
  35      *  - If isAlias is set:
  36      *      - namespace: Namespace this directive aliases to
  37      *      - name: Directive name this directive aliases to
  38      *
  39      * In certain degenerate cases, stdclass will actually be an integer. In
  40      * that case, the value is equivalent to an stdclass with the type
  41      * property set to the integer. If the integer is negative, type is
  42      * equal to the absolute value of integer, and allow_null is true.
  43      *
  44      * This class is friendly with HTMLPurifier_Config. If you need introspection
  45      * about the schema, you're better of using the ConfigSchema_Interchange,
  46      * which uses more memory but has much richer information.
  47      */
  48     public $info = array();
  49
  50     /**
  51      * Application-wide singleton
  52      */
  53     static protected $singleton;
  54
  55     public function __construct() {
  56         $this->defaultPlist = new HTMLPurifier_PropertyList();
  57     }
  58
  59     /**
  60      * Unserializes the default ConfigSchema.
  61      */
  62     public static function makeFromSerial() {
  63         return unserialize(file_get_contents(HTMLPURIFIER_PREFIX . '/HTMLPurifier/ConfigSchema/schema.ser'));
  64     }
  65
  66     /**
  67      * Retrieves an instance of the application-wide configuration definition.
  68      */
  69     public static function instance($prototype = null) {
  70         if ($prototype !== null) {
  71             HTMLPurifier_ConfigSchema::$singleton = $prototype;
  72         } elseif (HTMLPurifier_ConfigSchema::$singleton === null || $prototype === true) {
  73             HTMLPurifier_ConfigSchema::$singleton = HTMLPurifier_ConfigSchema::makeFromSerial();
  74         }
  75         return HTMLPurifier_ConfigSchema::$singleton;
  76     }
  77
  78     /**
  79      * Defines a directive for configuration
  80      * @warning Will fail of directive's namespace is defined.
  81      * @warning This method's signature is slightly different from the legacy
  82      *          define() static method! Beware!
  83      * @param $namespace Namespace the directive is in
  84      * @param $name Key of directive
  85      * @param $default Default value of directive
  86      * @param $type Allowed type of the directive. See
  87      *      HTMLPurifier_DirectiveDef::$type for allowed values
  88      * @param $allow_null Whether or not to allow null values
  89      */
  90     public function add($namespace, $name, $default, $type, $allow_null) {
  91         $obj = new stdclass();
  92         $obj->type = is_int($type) ? $type : HTMLPurifier_VarParser::$types[$type];
  93         if ($allow_null) $obj->allow_null = true;
  94         $this->info[$namespace][$name] = $obj;
  95         $this->defaults[$namespace][$name] = $default;
  96         $this->defaultPlist->set("$namespace.$name", $default);
  97     }
  98
  99     /**
 100      * Defines a namespace for directives to be put into.
 101      * @warning This is slightly different from the corresponding static
 102      *          method.
 103      * @param $namespace Namespace's name
 104      */
 105     public function addNamespace($namespace) {
 106         $this->info[$namespace] = array();
 107         $this->defaults[$namespace] = array();
 108     }
 109
 110     /**
 111      * Defines a directive value alias.
 112      *
 113      * Directive value aliases are convenient for developers because it lets
 114      * them set a directive to several values and get the same result.
 115      * @param $namespace Directive's namespace
 116      * @param $name Name of Directive
 117      * @param $aliases Hash of aliased values to the real alias
 118      */
 119     public function addValueAliases($namespace, $name, $aliases) {
 120         if (!isset($this->info[$namespace][$name]->aliases)) {
 121             $this->info[$namespace][$name]->aliases = array();
 122         }
 123         foreach ($aliases as $alias => $real) {
 124             $this->info[$namespace][$name]->aliases[$alias] = $real;
 125         }
 126     }
 127
 128     /**
 129      * Defines a set of allowed values for a directive.
 130      * @warning This is slightly different from the corresponding static
 131      *          method definition.
 132      * @param $namespace Namespace of directive
 133      * @param $name Name of directive
 134      * @param $allowed Lookup array of allowed values
 135      */
 136     public function addAllowedValues($namespace, $name, $allowed) {
 137         $this->info[$namespace][$name]->allowed = $allowed;
 138     }
 139
 140     /**
 141      * Defines a directive alias for backwards compatibility
 142      * @param $namespace
 143      * @param $name Directive that will be aliased
 144      * @param $new_namespace
 145      * @param $new_name Directive that the alias will be to
 146      */
 147     public function addAlias($namespace, $name, $new_namespace, $new_name) {
 148         $obj = new stdclass;
 149         $obj->namespace = $new_namespace;
 150         $obj->name = $new_name;
 151         $obj->isAlias = true;
 152         $this->info[$namespace][$name] = $obj;
 153     }
 154
 155     /**
 156      * Replaces any stdclass that only has the type property with type integer.
 157      */
 158     public function postProcess() {
 159         foreach ($this->info as $namespace => $info) {
 160             foreach ($info as $directive => $v) {
 161                 if (count((array) $v) == 1) {
 162                     $this->info[$namespace][$directive] = $v->type;
 163                 } elseif (count((array) $v) == 2 && isset($v->allow_null)) {
 164                     $this->info[$namespace][$directive] = -$v->type;
 165                 }
 166             }
 167         }
 168     }
 169
 170     // DEPRECATED METHODS
 171
 172     /** @see HTMLPurifier_ConfigSchema->set() */
 173     public static function define($namespace, $name, $default, $type, $description) {
 174         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 175         $type_values = explode('/', $type, 2);
 176         $type = $type_values[0];
 177         $modifier = isset($type_values[1]) ? $type_values[1] : false;
 178         $allow_null = ($modifier === 'null');
 179         $def = HTMLPurifier_ConfigSchema::instance();
 180         $def->add($namespace, $name, $default, $type, $allow_null);
 181     }
 182
 183     /** @see HTMLPurifier_ConfigSchema->addNamespace() */
 184     public static function defineNamespace($namespace, $description) {
 185         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 186         $def = HTMLPurifier_ConfigSchema::instance();
 187         $def->addNamespace($namespace);
 188     }
 189
 190     /** @see HTMLPurifier_ConfigSchema->addValueAliases() */
 191     public static function defineValueAliases($namespace, $name, $aliases) {
 192         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 193         $def = HTMLPurifier_ConfigSchema::instance();
 194         $def->addValueAliases($namespace, $name, $aliases);
 195     }
 196
 197     /** @see HTMLPurifier_ConfigSchema->addAllowedValues() */
 198     public static function defineAllowedValues($namespace, $name, $allowed_values) {
 199         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 200         $allowed = array();
 201         foreach ($allowed_values as $value) {
 202             $allowed[$value] = true;
 203         }
 204         $def = HTMLPurifier_ConfigSchema::instance();
 205         $def->addAllowedValues($namespace, $name, $allowed);
 206     }
 207
 208     /** @see HTMLPurifier_ConfigSchema->addAlias() */
 209     public static function defineAlias($namespace, $name, $new_namespace, $new_name) {
 210         HTMLPurifier_ConfigSchema::deprecated(__METHOD__);
 211         $def = HTMLPurifier_ConfigSchema::instance();
 212         $def->addAlias($namespace, $name, $new_namespace, $new_name);
 213     }
 214
 215     /** @deprecated, use HTMLPurifier_VarParser->parse() */
 216     public function validate($a, $b, $c = false) {
 217         trigger_error("HTMLPurifier_ConfigSchema->validate deprecated, use HTMLPurifier_VarParser->parse instead", E_USER_NOTICE);
 218         $parser = new HTMLPurifier_VarParser();
 219         return $parser->parse($a, $b, $c);
 220     }
 221
 222     /**
 223      * Throws an E_USER_NOTICE stating that a method is deprecated.
 224      */
 225     private static function deprecated($method) {
 226         trigger_error("Static HTMLPurifier_ConfigSchema::$method deprecated, use add*() method instead", E_USER_NOTICE);
 227     }
 228
 229 }
 230
 231 // vim: et sw=4 sts=4