]> git.mxchange.org Git - friendica.git/blob - library/HTMLPurifier/Config.php
more friend suggestions
[friendica.git] / 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