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