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
21 * HTML Purifier's version
23 public $version = '3.1.0';
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
34 * Namespace indexed array of serials for specific namespaces (see
35 * getSerial() for more info).
37 protected $serials = array();
40 * Serial for entire configuration object
45 * Two-level associative array of configuration directives
50 * Parser for variables
55 * Reference HTMLPurifier_ConfigSchema for value checking
56 * @note This is public for introspective purposes. Please don't
62 * Indexed array of definitions
64 protected $definitions;
67 * Bool indicator whether or not config is finalized
69 protected $finalized = false;
72 * @param $definition HTMLPurifier_ConfigSchema that defines what directives
75 public function __construct($definition) {
76 $this->conf
= $definition->defaults
; // set up, copy in defaults
77 $this->def
= $definition; // keep a copy around for checking
78 $this->parser
= new HTMLPurifier_VarParser_Flexible();
82 * Convenience constructor that creates a config object based on a mixed var
83 * @param mixed $config Variable that defines the state of the config
84 * object. Can be: a HTMLPurifier_Config() object,
85 * an array of directives based on loadArray(),
86 * or a string filename of an ini file.
87 * @param HTMLPurifier_ConfigSchema Schema object
88 * @return Configured HTMLPurifier_Config object
90 public static function create($config, $schema = null) {
91 if ($config instanceof HTMLPurifier_Config
) {
96 $ret = HTMLPurifier_Config
::createDefault();
98 $ret = new HTMLPurifier_Config($schema);
100 if (is_string($config)) $ret->loadIni($config);
101 elseif (is_array($config)) $ret->loadArray($config);
106 * Convenience constructor that creates a default configuration object.
107 * @return Default HTMLPurifier_Config object.
109 public static function createDefault() {
110 $definition = HTMLPurifier_ConfigSchema
::instance();
111 $config = new HTMLPurifier_Config($definition);
116 * Retreives a value from the configuration.
117 * @param $namespace String namespace
118 * @param $key String key
120 public function get($namespace, $key) {
121 if (!$this->finalized
&& $this->autoFinalize
) $this->finalize();
122 if (!isset($this->def
->info
[$namespace][$key])) {
123 // can't add % due to SimpleTest bug
124 trigger_error('Cannot retrieve value of undefined directive ' . htmlspecialchars("$namespace.$key"),
128 if (isset($this->def
->info
[$namespace][$key]->isAlias
)) {
129 $d = $this->def
->info
[$namespace][$key];
130 trigger_error('Cannot get value from aliased directive, use real name ' . $d->namespace . '.' . $d->name
,
134 return $this->conf
[$namespace][$key];
138 * Retreives an array of directives to values from a given namespace
139 * @param $namespace String namespace
141 public function getBatch($namespace) {
142 if (!$this->finalized
&& $this->autoFinalize
) $this->finalize();
143 if (!isset($this->def
->info
[$namespace])) {
144 trigger_error('Cannot retrieve undefined namespace ' . htmlspecialchars($namespace),
148 return $this->conf
[$namespace];
152 * Returns a md5 signature of a segment of the configuration object
153 * that uniquely identifies that particular configuration
154 * @note Revision is handled specially and is removed from the batch
156 * @param $namespace Namespace to get serial for
158 public function getBatchSerial($namespace) {
159 if (empty($this->serials
[$namespace])) {
160 $batch = $this->getBatch($namespace);
161 unset($batch['DefinitionRev']);
162 $this->serials
[$namespace] = md5(serialize($batch));
164 return $this->serials
[$namespace];
168 * Returns a md5 signature for the entire configuration object
169 * that uniquely identifies that particular configuration
171 public function getSerial() {
172 if (empty($this->serial
)) {
173 $this->serial
= md5(serialize($this->getAll()));
175 return $this->serial
;
179 * Retrieves all directives, organized by namespace
181 public function getAll() {
182 if (!$this->finalized
&& $this->autoFinalize
) $this->finalize();
187 * Sets a value to configuration.
188 * @param $namespace String namespace
189 * @param $key String key
190 * @param $value Mixed value
192 public function set($namespace, $key, $value, $from_alias = false) {
193 if ($this->isFinalized('Cannot set directive after finalization')) return;
194 if (!isset($this->def
->info
[$namespace][$key])) {
195 trigger_error('Cannot set undefined directive ' . htmlspecialchars("$namespace.$key") . ' to value',
199 if (isset($this->def
->info
[$namespace][$key]->isAlias
)) {
201 trigger_error('Double-aliases not allowed, please fix '.
202 'ConfigSchema bug with' . "$namespace.$key", E_USER_ERROR
);
205 $this->set($new_ns = $this->def
->info
[$namespace][$key]->namespace,
206 $new_dir = $this->def
->info
[$namespace][$key]->name
,
208 trigger_error("$namespace.$key is an alias, preferred directive name is $new_ns.$new_dir", E_USER_NOTICE
);
212 $value = $this->parser
->parse(
214 $type = $this->def
->info
[$namespace][$key]->type
,
215 isset($this->def
->info
[$namespace][$key]->allow_null
)
217 } catch (HTMLPurifier_VarParserException
$e) {
218 trigger_error('Value for ' . "$namespace.$key" . ' is of invalid type, should be ' . HTMLPurifier_VarParser
::getTypeName($type), E_USER_WARNING
);
221 if (is_string($value)) {
222 // resolve value alias if defined
223 if (isset($this->def
->info
[$namespace][$key]->aliases
[$value])) {
224 $value = $this->def
->info
[$namespace][$key]->aliases
[$value];
226 if (isset($this->def
->info
[$namespace][$key])) {
227 // check to see if the value is allowed
228 if (isset($this->def
->info
[$namespace][$key]->allowed
) && !isset($this->def
->info
[$namespace][$key]->allowed
[$value])) {
229 trigger_error('Value not supported, valid values are: ' .
230 $this->_listify($this->def
->info
[$namespace][$key]->allowed
), E_USER_WARNING
);
235 $this->conf
[$namespace][$key] = $value;
237 // reset definitions if the directives they depend on changed
238 // this is a very costly process, so it's discouraged
240 if ($namespace == 'HTML' ||
$namespace == 'CSS') {
241 $this->definitions
[$namespace] = null;
244 $this->serials
[$namespace] = false;
248 * Convenience function for error reporting
250 private function _listify($lookup) {
252 foreach ($lookup as $name => $b) $list[] = $name;
253 return implode(', ', $list);
257 * Retrieves object reference to the HTML definition.
258 * @param $raw Return a copy that has not been setup yet. Must be
259 * called before it's been setup, otherwise won't work.
261 public function getHTMLDefinition($raw = false) {
262 return $this->getDefinition('HTML', $raw);
266 * Retrieves object reference to the CSS definition
267 * @param $raw Return a copy that has not been setup yet. Must be
268 * called before it's been setup, otherwise won't work.
270 public function getCSSDefinition($raw = false) {
271 return $this->getDefinition('CSS', $raw);
275 * Retrieves a definition
276 * @param $type Type of definition: HTML, CSS, etc
277 * @param $raw Whether or not definition should be returned raw
279 public function getDefinition($type, $raw = false) {
280 if (!$this->finalized
&& $this->autoFinalize
) $this->finalize();
281 $factory = HTMLPurifier_DefinitionCacheFactory
::instance();
282 $cache = $factory->create($type, $this);
284 // see if we can quickly supply a definition
285 if (!empty($this->definitions
[$type])) {
286 if (!$this->definitions
[$type]->setup
) {
287 $this->definitions
[$type]->setup($this);
288 $cache->set($this->definitions
[$type], $this);
290 return $this->definitions
[$type];
292 // memory check missed, try cache
293 $this->definitions
[$type] = $cache->get($this);
294 if ($this->definitions
[$type]) {
295 // definition in cache, return it
296 return $this->definitions
[$type];
299 !empty($this->definitions
[$type]) &&
300 !$this->definitions
[$type]->setup
302 // raw requested, raw in memory, quick return
303 return $this->definitions
[$type];
305 // quick checks failed, let's create the object
306 if ($type == 'HTML') {
307 $this->definitions
[$type] = new HTMLPurifier_HTMLDefinition();
308 } elseif ($type == 'CSS') {
309 $this->definitions
[$type] = new HTMLPurifier_CSSDefinition();
310 } elseif ($type == 'URI') {
311 $this->definitions
[$type] = new HTMLPurifier_URIDefinition();
313 throw new HTMLPurifier_Exception("Definition of $type type not supported");
315 // quick abort if raw
317 if (is_null($this->get($type, 'DefinitionID'))) {
318 // fatally error out if definition ID not set
319 throw new HTMLPurifier_Exception("Cannot retrieve raw version without specifying %$type.DefinitionID");
321 return $this->definitions
[$type];
324 $this->definitions
[$type]->setup($this);
326 $cache->set($this->definitions
[$type], $this);
327 return $this->definitions
[$type];
331 * Loads configuration values from an array with the following structure:
332 * Namespace.Directive => Value
333 * @param $config_array Configuration associative array
335 public function loadArray($config_array) {
336 if ($this->isFinalized('Cannot load directives after finalization')) return;
337 foreach ($config_array as $key => $value) {
338 $key = str_replace('_', '.', $key);
339 if (strpos($key, '.') !== false) {
341 list($namespace, $directive) = explode('.', $key);
342 $this->set($namespace, $directive, $value);
345 $namespace_values = $value;
346 foreach ($namespace_values as $directive => $value) {
347 $this->set($namespace, $directive, $value);
354 * Returns a list of array(namespace, directive) for all directives
355 * that are allowed in a web-form context as per an allowed
356 * namespaces/directives list.
357 * @param $allowed List of allowed namespaces/directives
359 public static function getAllowedDirectivesForForm($allowed, $schema = null) {
361 $schema = HTMLPurifier_ConfigSchema
::instance();
363 if ($allowed !== true) {
364 if (is_string($allowed)) $allowed = array($allowed);
365 $allowed_ns = array();
366 $allowed_directives = array();
367 $blacklisted_directives = array();
368 foreach ($allowed as $ns_or_directive) {
369 if (strpos($ns_or_directive, '.') !== false) {
371 if ($ns_or_directive[0] == '-') {
372 $blacklisted_directives[substr($ns_or_directive, 1)] = true;
374 $allowed_directives[$ns_or_directive] = true;
378 $allowed_ns[$ns_or_directive] = true;
383 foreach ($schema->info
as $ns => $keypairs) {
384 foreach ($keypairs as $directive => $def) {
385 if ($allowed !== true) {
386 if (isset($blacklisted_directives["$ns.$directive"])) continue;
387 if (!isset($allowed_directives["$ns.$directive"]) && !isset($allowed_ns[$ns])) continue;
389 if (isset($def->isAlias
)) continue;
390 if ($directive == 'DefinitionID' ||
$directive == 'DefinitionRev') continue;
391 $ret[] = array($ns, $directive);
398 * Loads configuration values from $_GET/$_POST that were posted
400 * @param $array $_GET or $_POST array to import
401 * @param $index Index/name that the config variables are in
402 * @param $allowed List of allowed namespaces/directives
403 * @param $mq_fix Boolean whether or not to enable magic quotes fix
404 * @param $schema Instance of HTMLPurifier_ConfigSchema to use, if not global copy
406 public static function loadArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) {
407 $ret = HTMLPurifier_Config
::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $schema);
408 $config = HTMLPurifier_Config
::create($ret, $schema);
413 * Merges in configuration values from $_GET/$_POST to object. NOT STATIC.
414 * @note Same parameters as loadArrayFromForm
416 public function mergeArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true) {
417 $ret = HTMLPurifier_Config
::prepareArrayFromForm($array, $index, $allowed, $mq_fix, $this->def
);
418 $this->loadArray($ret);
422 * Prepares an array from a form into something usable for the more
423 * strict parts of HTMLPurifier_Config
425 public static function prepareArrayFromForm($array, $index = false, $allowed = true, $mq_fix = true, $schema = null) {
426 if ($index !== false) $array = (isset($array[$index]) && is_array($array[$index])) ?
$array[$index] : array();
427 $mq = $mq_fix && function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc();
429 $allowed = HTMLPurifier_Config
::getAllowedDirectivesForForm($allowed, $schema);
431 foreach ($allowed as $key) {
432 list($ns, $directive) = $key;
433 $skey = "$ns.$directive";
434 if (!empty($array["Null_$skey"])) {
435 $ret[$ns][$directive] = null;
438 if (!isset($array[$skey])) continue;
439 $value = $mq ?
stripslashes($array[$skey]) : $array[$skey];
440 $ret[$ns][$directive] = $value;
446 * Loads configuration values from an ini file
447 * @param $filename Name of ini file
449 public function loadIni($filename) {
450 if ($this->isFinalized('Cannot load directives after finalization')) return;
451 $array = parse_ini_file($filename, true);
452 $this->loadArray($array);
456 * Checks whether or not the configuration object is finalized.
457 * @param $error String error message, or false for no error
459 public function isFinalized($error = false) {
460 if ($this->finalized
&& $error) {
461 trigger_error($error, E_USER_ERROR
);
463 return $this->finalized
;
467 * Finalizes configuration only if auto finalize is on and not
470 public function autoFinalize() {
471 if (!$this->finalized
&& $this->autoFinalize
) $this->finalize();
475 * Finalizes a configuration object, prohibiting further change
477 public function finalize() {
478 $this->finalized
= true;