library/HTMLPurifier/ElementDef.php

   1 <?php
   2
   3 /**
   4  * Structure that stores an HTML element definition. Used by
   5  * HTMLPurifier_HTMLDefinition and HTMLPurifier_HTMLModule.
   6  * @note This class is inspected by HTMLPurifier_Printer_HTMLDefinition.
   7  *       Please update that class too.
   8  * @warning If you add new properties to this class, you MUST update
   9  *          the mergeIn() method.
  10  */
  11 class HTMLPurifier_ElementDef
  12 {
  13
  14     /**
  15      * Does the definition work by itself, or is it created solely
  16      * for the purpose of merging into another definition?
  17      */
  18     public $standalone = true;
  19
  20     /**
  21      * Associative array of attribute name to HTMLPurifier_AttrDef
  22      * @note Before being processed by HTMLPurifier_AttrCollections
  23      *       when modules are finalized during
  24      *       HTMLPurifier_HTMLDefinition->setup(), this array may also
  25      *       contain an array at index 0 that indicates which attribute
  26      *       collections to load into the full array. It may also
  27      *       contain string indentifiers in lieu of HTMLPurifier_AttrDef,
  28      *       see HTMLPurifier_AttrTypes on how they are expanded during
  29      *       HTMLPurifier_HTMLDefinition->setup() processing.
  30      */
  31     public $attr = array();
  32
  33     // XXX: Design note: currently, it's not possible to override
  34     // previously defined AttrTransforms without messing around with
  35     // the final generated config. This is by design; a previous version
  36     // used an associated list of attr_transform, but it was extremely
  37     // easy to accidentally override other attribute transforms by
  38     // forgetting to specify an index (and just using 0.)  While we
  39     // could check this by checking the index number and complaining,
  40     // there is a second problem which is that it is not at all easy to
  41     // tell when something is getting overridden. Combine this with a
  42     // codebase where this isn't really being used, and it's perfect for
  43     // nuking.
  44
  45     /**
  46      * List of tags HTMLPurifier_AttrTransform to be done before validation
  47      */
  48     public $attr_transform_pre = array();
  49
  50     /**
  51      * List of tags HTMLPurifier_AttrTransform to be done after validation
  52      */
  53     public $attr_transform_post = array();
  54
  55     /**
  56      * HTMLPurifier_ChildDef of this tag.
  57      */
  58     public $child;
  59
  60     /**
  61      * Abstract string representation of internal ChildDef rules. See
  62      * HTMLPurifier_ContentSets for how this is parsed and then transformed
  63      * into an HTMLPurifier_ChildDef.
  64      * @warning This is a temporary variable that is not available after
  65      *      being processed by HTMLDefinition
  66      */
  67     public $content_model;
  68
  69     /**
  70      * Value of $child->type, used to determine which ChildDef to use,
  71      * used in combination with $content_model.
  72      * @warning This must be lowercase
  73      * @warning This is a temporary variable that is not available after
  74      *      being processed by HTMLDefinition
  75      */
  76     public $content_model_type;
  77
  78
  79
  80     /**
  81      * Does the element have a content model (#PCDATA | Inline)*? This
  82      * is important for chameleon ins and del processing in
  83      * HTMLPurifier_ChildDef_Chameleon. Dynamically set: modules don't
  84      * have to worry about this one.
  85      */
  86     public $descendants_are_inline = false;
  87
  88     /**
  89      * List of the names of required attributes this element has. Dynamically
  90      * populated by HTMLPurifier_HTMLDefinition::getElement
  91      */
  92     public $required_attr = array();
  93
  94     /**
  95      * Lookup table of tags excluded from all descendants of this tag.
  96      * @note SGML permits exclusions for all descendants, but this is
  97      *       not possible with DTDs or XML Schemas. W3C has elected to
  98      *       use complicated compositions of content_models to simulate
  99      *       exclusion for children, but we go the simpler, SGML-style
 100      *       route of flat-out exclusions, which correctly apply to
 101      *       all descendants and not just children. Note that the XHTML
 102      *       Modularization Abstract Modules are blithely unaware of such
 103      *       distinctions.
 104      */
 105     public $excludes = array();
 106
 107     /**
 108      * This tag is explicitly auto-closed by the following tags.
 109      */
 110     public $autoclose = array();
 111
 112     /**
 113      * If a foreign element is found in this element, test if it is
 114      * allowed by this sub-element; if it is, instead of closing the
 115      * current element, place it inside this element.
 116      */
 117     public $wrap;
 118
 119     /**
 120      * Whether or not this is a formatting element affected by the
 121      * "Active Formatting Elements" algorithm.
 122      */
 123     public $formatting;
 124
 125     /**
 126      * Low-level factory constructor for creating new standalone element defs
 127      */
 128     public static function create($content_model, $content_model_type, $attr) {
 129         $def = new HTMLPurifier_ElementDef();
 130         $def->content_model = $content_model;
 131         $def->content_model_type = $content_model_type;
 132         $def->attr = $attr;
 133         return $def;
 134     }
 135
 136     /**
 137      * Merges the values of another element definition into this one.
 138      * Values from the new element def take precedence if a value is
 139      * not mergeable.
 140      */
 141     public function mergeIn($def) {
 142
 143         // later keys takes precedence
 144         foreach($def->attr as $k => $v) {
 145             if ($k === 0) {
 146                 // merge in the includes
 147                 // sorry, no way to override an include
 148                 foreach ($v as $v2) {
 149                     $this->attr[0][] = $v2;
 150                 }
 151                 continue;
 152             }
 153             if ($v === false) {
 154                 if (isset($this->attr[$k])) unset($this->attr[$k]);
 155                 continue;
 156             }
 157             $this->attr[$k] = $v;
 158         }
 159         $this->_mergeAssocArray($this->excludes, $def->excludes);
 160         $this->attr_transform_pre = array_merge($this->attr_transform_pre, $def->attr_transform_pre);
 161         $this->attr_transform_post = array_merge($this->attr_transform_post, $def->attr_transform_post);
 162
 163         if(!empty($def->content_model)) {
 164             $this->content_model =
 165                 str_replace("#SUPER", $this->content_model, $def->content_model);
 166             $this->child = false;
 167         }
 168         if(!empty($def->content_model_type)) {
 169             $this->content_model_type = $def->content_model_type;
 170             $this->child = false;
 171         }
 172         if(!is_null($def->child)) $this->child = $def->child;
 173         if(!is_null($def->formatting)) $this->formatting = $def->formatting;
 174         if($def->descendants_are_inline) $this->descendants_are_inline = $def->descendants_are_inline;
 175
 176     }
 177
 178     /**
 179      * Merges one array into another, removes values which equal false
 180      * @param $a1 Array by reference that is merged into
 181      * @param $a2 Array that merges into $a1
 182      */
 183     private function _mergeAssocArray(&$a1, $a2) {
 184         foreach ($a2 as $k => $v) {
 185             if ($v === false) {
 186                 if (isset($a1[$k])) unset($a1[$k]);
 187                 continue;
 188             }
 189             $a1[$k] = $v;
 190         }
 191     }
 192
 193 }
 194
 195 // vim: et sw=4 sts=4