library/HTMLPurifier/HTMLModule.php

   1 <?php
   2
   3 /**
   4  * Represents an XHTML 1.1 module, with information on elements, tags
   5  * and attributes.
   6  * @note Even though this is technically XHTML 1.1, it is also used for
   7  *       regular HTML parsing. We are using modulization as a convenient
   8  *       way to represent the internals of HTMLDefinition, and our
   9  *       implementation is by no means conforming and does not directly
  10  *       use the normative DTDs or XML schemas.
  11  * @note The public variables in a module should almost directly
  12  *       correspond to the variables in HTMLPurifier_HTMLDefinition.
  13  *       However, the prefix info carries no special meaning in these
  14  *       objects (include it anyway if that's the correspondence though).
  15  * @todo Consider making some member functions protected
  16  */
  17
  18 class HTMLPurifier_HTMLModule
  19 {
  20
  21     // -- Overloadable ----------------------------------------------------
  22
  23     /**
  24      * Short unique string identifier of the module
  25      */
  26     public $name;
  27
  28     /**
  29      * Informally, a list of elements this module changes. Not used in
  30      * any significant way.
  31      */
  32     public $elements = array();
  33
  34     /**
  35      * Associative array of element names to element definitions.
  36      * Some definitions may be incomplete, to be merged in later
  37      * with the full definition.
  38      */
  39     public $info = array();
  40
  41     /**
  42      * Associative array of content set names to content set additions.
  43      * This is commonly used to, say, add an A element to the Inline
  44      * content set. This corresponds to an internal variable $content_sets
  45      * and NOT info_content_sets member variable of HTMLDefinition.
  46      */
  47     public $content_sets = array();
  48
  49     /**
  50      * Associative array of attribute collection names to attribute
  51      * collection additions. More rarely used for adding attributes to
  52      * the global collections. Example is the StyleAttribute module adding
  53      * the style attribute to the Core. Corresponds to HTMLDefinition's
  54      * attr_collections->info, since the object's data is only info,
  55      * with extra behavior associated with it.
  56      */
  57     public $attr_collections = array();
  58
  59     /**
  60      * Associative array of deprecated tag name to HTMLPurifier_TagTransform
  61      */
  62     public $info_tag_transform = array();
  63
  64     /**
  65      * List of HTMLPurifier_AttrTransform to be performed before validation.
  66      */
  67     public $info_attr_transform_pre = array();
  68
  69     /**
  70      * List of HTMLPurifier_AttrTransform to be performed after validation.
  71      */
  72     public $info_attr_transform_post = array();
  73
  74     /**
  75      * List of HTMLPurifier_Injector to be performed during well-formedness fixing.
  76      * An injector will only be invoked if all of it's pre-requisites are met;
  77      * if an injector fails setup, there will be no error; it will simply be
  78      * silently disabled.
  79      */
  80     public $info_injector = array();
  81
  82     /**
  83      * Boolean flag that indicates whether or not getChildDef is implemented.
  84      * For optimization reasons: may save a call to a function. Be sure
  85      * to set it if you do implement getChildDef(), otherwise it will have
  86      * no effect!
  87      */
  88     public $defines_child_def = false;
  89
  90     /**
  91      * Boolean flag whether or not this module is safe. If it is not safe, all
  92      * of its members are unsafe. Modules are safe by default (this might be
  93      * slightly dangerous, but it doesn't make much sense to force HTML Purifier,
  94      * which is based off of safe HTML, to explicitly say, "This is safe," even
  95      * though there are modules which are "unsafe")
  96      *
  97      * @note Previously, safety could be applied at an element level granularity.
  98      *       We've removed this ability, so in order to add "unsafe" elements
  99      *       or attributes, a dedicated module with this property set to false
 100      *       must be used.
 101      */
 102     public $safe = true;
 103
 104     /**
 105      * Retrieves a proper HTMLPurifier_ChildDef subclass based on
 106      * content_model and content_model_type member variables of
 107      * the HTMLPurifier_ElementDef class. There is a similar function
 108      * in HTMLPurifier_HTMLDefinition.
 109      * @param $def HTMLPurifier_ElementDef instance
 110      * @return HTMLPurifier_ChildDef subclass
 111      */
 112     public function getChildDef($def) {return false;}
 113
 114     // -- Convenience -----------------------------------------------------
 115
 116     /**
 117      * Convenience function that sets up a new element
 118      * @param $element Name of element to add
 119      * @param $type What content set should element be registered to?
 120      *              Set as false to skip this step.
 121      * @param $contents Allowed children in form of:
 122      *              "$content_model_type: $content_model"
 123      * @param $attr_includes What attribute collections to register to
 124      *              element?
 125      * @param $attr What unique attributes does the element define?
 126      * @note See ElementDef for in-depth descriptions of these parameters.
 127      * @return Created element definition object, so you
 128      *         can set advanced parameters
 129      */
 130     public function addElement($element, $type, $contents, $attr_includes = array(), $attr = array()) {
 131         $this->elements[] = $element;
 132         // parse content_model
 133         list($content_model_type, $content_model) = $this->parseContents($contents);
 134         // merge in attribute inclusions
 135         $this->mergeInAttrIncludes($attr, $attr_includes);
 136         // add element to content sets
 137         if ($type) $this->addElementToContentSet($element, $type);
 138         // create element
 139         $this->info[$element] = HTMLPurifier_ElementDef::create(
 140             $content_model, $content_model_type, $attr
 141         );
 142         // literal object $contents means direct child manipulation
 143         if (!is_string($contents)) $this->info[$element]->child = $contents;
 144         return $this->info[$element];
 145     }
 146
 147     /**
 148      * Convenience function that creates a totally blank, non-standalone
 149      * element.
 150      * @param $element Name of element to create
 151      * @return Created element
 152      */
 153     public function addBlankElement($element) {
 154         if (!isset($this->info[$element])) {
 155             $this->elements[] = $element;
 156             $this->info[$element] = new HTMLPurifier_ElementDef();
 157             $this->info[$element]->standalone = false;
 158         } else {
 159             trigger_error("Definition for $element already exists in module, cannot redefine");
 160         }
 161         return $this->info[$element];
 162     }
 163
 164     /**
 165      * Convenience function that registers an element to a content set
 166      * @param Element to register
 167      * @param Name content set (warning: case sensitive, usually upper-case
 168      *        first letter)
 169      */
 170     public function addElementToContentSet($element, $type) {
 171         if (!isset($this->content_sets[$type])) $this->content_sets[$type] = '';
 172         else $this->content_sets[$type] .= ' | ';
 173         $this->content_sets[$type] .= $element;
 174     }
 175
 176     /**
 177      * Convenience function that transforms single-string contents
 178      * into separate content model and content model type
 179      * @param $contents Allowed children in form of:
 180      *                  "$content_model_type: $content_model"
 181      * @note If contents is an object, an array of two nulls will be
 182      *       returned, and the callee needs to take the original $contents
 183      *       and use it directly.
 184      */
 185     public function parseContents($contents) {
 186         if (!is_string($contents)) return array(null, null); // defer
 187         switch ($contents) {
 188             // check for shorthand content model forms
 189             case 'Empty':
 190                 return array('empty', '');
 191             case 'Inline':
 192                 return array('optional', 'Inline | #PCDATA');
 193             case 'Flow':
 194                 return array('optional', 'Flow | #PCDATA');
 195         }
 196         list($content_model_type, $content_model) = explode(':', $contents);
 197         $content_model_type = strtolower(trim($content_model_type));
 198         $content_model = trim($content_model);
 199         return array($content_model_type, $content_model);
 200     }
 201
 202     /**
 203      * Convenience function that merges a list of attribute includes into
 204      * an attribute array.
 205      * @param $attr Reference to attr array to modify
 206      * @param $attr_includes Array of includes / string include to merge in
 207      */
 208     public function mergeInAttrIncludes(&$attr, $attr_includes) {
 209         if (!is_array($attr_includes)) {
 210             if (empty($attr_includes)) $attr_includes = array();
 211             else $attr_includes = array($attr_includes);
 212         }
 213         $attr[0] = $attr_includes;
 214     }
 215
 216     /**
 217      * Convenience function that generates a lookup table with boolean
 218      * true as value.
 219      * @param $list List of values to turn into a lookup
 220      * @note You can also pass an arbitrary number of arguments in
 221      *       place of the regular argument
 222      * @return Lookup array equivalent of list
 223      */
 224     public function makeLookup($list) {
 225         if (is_string($list)) $list = func_get_args();
 226         $ret = array();
 227         foreach ($list as $value) {
 228             if (is_null($value)) continue;
 229             $ret[$value] = true;
 230         }
 231         return $ret;
 232     }
 233
 234     /**
 235      * Lazy load construction of the module after determining whether
 236      * or not it's needed, and also when a finalized configuration object
 237      * is available.
 238      * @param $config Instance of HTMLPurifier_Config
 239      */
 240     public function setup($config) {}
 241
 242 }
 243
 244 // vim: et sw=4 sts=4