[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Injects tokens into the document while parsing for well-formedness.
   5   * This enables "formatter-like" functionality such as auto-paragraphing,
   6   * smiley-ification and linkification to take place.
   7   *
   8   * A note on how handlers create changes; this is done by assigning a new
   9   * value to the $token reference. These values can take a variety of forms and
  10   * are best described HTMLPurifier_Strategy_MakeWellFormed->processToken()
  11   * documentation.
  12   *
  13   * @todo Allow injectors to request a re-run on their output. This
  14   *       would help if an operation is recursive.
  15   */
  16  abstract class HTMLPurifier_Injector
  17  {
  18  
  19      /**
  20       * Advisory name of injector, this is for friendly error messages
  21       */
  22      public $name;
  23  
  24      /**
  25       * Instance of HTMLPurifier_HTMLDefinition
  26       */
  27      protected $htmlDefinition;
  28  
  29      /**
  30       * Reference to CurrentNesting variable in Context. This is an array
  31       * list of tokens that we are currently "inside"
  32       */
  33      protected $currentNesting;
  34  
  35      /**
  36       * Reference to InputTokens variable in Context. This is an array
  37       * list of the input tokens that are being processed.
  38       */
  39      protected $inputTokens;
  40  
  41      /**
  42       * Reference to InputIndex variable in Context. This is an integer
  43       * array index for $this->inputTokens that indicates what token
  44       * is currently being processed.
  45       */
  46      protected $inputIndex;
  47  
  48      /**
  49       * Array of elements and attributes this injector creates and therefore
  50       * need to be allowed by the definition. Takes form of
  51       * array('element' => array('attr', 'attr2'), 'element2')
  52       */
  53      public $needed = array();
  54  
  55      /**
  56       * Index of inputTokens to rewind to.
  57       */
  58      protected $rewind = false;
  59  
  60      /**
  61       * Rewind to a spot to re-perform processing. This is useful if you
  62       * deleted a node, and now need to see if this change affected any
  63       * earlier nodes. Rewinding does not affect other injectors, and can
  64       * result in infinite loops if not used carefully.
  65       * @warning HTML Purifier will prevent you from fast-forwarding with this
  66       *          function.
  67       */
  68      public function rewind($index) {
  69          $this->rewind = $index;
  70      }
  71  
  72      /**
  73       * Retrieves rewind, and then unsets it.
  74       */
  75      public function getRewind() {
  76          $r = $this->rewind;
  77          $this->rewind = false;
  78          return $r;
  79      }
  80  
  81      /**
  82       * Prepares the injector by giving it the config and context objects:
  83       * this allows references to important variables to be made within
  84       * the injector. This function also checks if the HTML environment
  85       * will work with the Injector (see checkNeeded()).
  86       * @param $config Instance of HTMLPurifier_Config
  87       * @param $context Instance of HTMLPurifier_Context
  88       * @return Boolean false if success, string of missing needed element/attribute if failure
  89       */
  90      public function prepare($config, $context) {
  91          $this->htmlDefinition = $config->getHTMLDefinition();
  92          // Even though this might fail, some unit tests ignore this and
  93          // still test checkNeeded, so be careful. Maybe get rid of that
  94          // dependency.
  95          $result = $this->checkNeeded($config);
  96          if ($result !== false) return $result;
  97          $this->currentNesting =& $context->get('CurrentNesting');
  98          $this->inputTokens    =& $context->get('InputTokens');
  99          $this->inputIndex     =& $context->get('InputIndex');
 100          return false;
 101      }
 102  
 103      /**
 104       * This function checks if the HTML environment
 105       * will work with the Injector: if p tags are not allowed, the
 106       * Auto-Paragraphing injector should not be enabled.
 107       * @param $config Instance of HTMLPurifier_Config
 108       * @param $context Instance of HTMLPurifier_Context
 109       * @return Boolean false if success, string of missing needed element/attribute if failure
 110       */
 111      public function checkNeeded($config) {
 112          $def = $config->getHTMLDefinition();
 113          foreach ($this->needed as $element => $attributes) {
 114              if (is_int($element)) $element = $attributes;
 115              if (!isset($def->info[$element])) return $element;
 116              if (!is_array($attributes)) continue;
 117              foreach ($attributes as $name) {
 118                  if (!isset($def->info[$element]->attr[$name])) return "$element.$name";
 119              }
 120          }
 121          return false;
 122      }
 123  
 124      /**
 125       * Tests if the context node allows a certain element
 126       * @param $name Name of element to test for
 127       * @return True if element is allowed, false if it is not
 128       */
 129      public function allowsElement($name) {
 130          if (!empty($this->currentNesting)) {
 131              $parent_token = array_pop($this->currentNesting);
 132              $this->currentNesting[] = $parent_token;
 133              $parent = $this->htmlDefinition->info[$parent_token->name];
 134          } else {
 135              $parent = $this->htmlDefinition->info_parent_def;
 136          }
 137          if (!isset($parent->child->elements[$name]) || isset($parent->excludes[$name])) {
 138              return false;
 139          }
 140          return true;
 141      }
 142  
 143      /**
 144       * Iterator function, which starts with the next token and continues until
 145       * you reach the end of the input tokens.
 146       * @warning Please prevent previous references from interfering with this
 147       *          functions by setting $i = null beforehand!
 148       * @param &$i Current integer index variable for inputTokens
 149       * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
 150       */
 151      protected function forward(&$i, &$current) {
 152          if ($i === null) $i = $this->inputIndex + 1;
 153          else $i++;
 154          if (!isset($this->inputTokens[$i])) return false;
 155          $current = $this->inputTokens[$i];
 156          return true;
 157      }
 158  
 159      /**
 160       * Similar to _forward, but accepts a third parameter $nesting (which
 161       * should be initialized at 0) and stops when we hit the end tag
 162       * for the node $this->inputIndex starts in.
 163       */
 164      protected function forwardUntilEndToken(&$i, &$current, &$nesting) {
 165          $result = $this->forward($i, $current);
 166          if (!$result) return false;
 167          if ($nesting === null) $nesting = 0;
 168          if     ($current instanceof HTMLPurifier_Token_Start) $nesting++;
 169          elseif ($current instanceof HTMLPurifier_Token_End) {
 170              if ($nesting <= 0) return false;
 171              $nesting--;
 172          }
 173          return true;
 174      }
 175  
 176      /**
 177       * Iterator function, starts with the previous token and continues until
 178       * you reach the beginning of input tokens.
 179       * @warning Please prevent previous references from interfering with this
 180       *          functions by setting $i = null beforehand!
 181       * @param &$i Current integer index variable for inputTokens
 182       * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
 183       */
 184      protected function backward(&$i, &$current) {
 185          if ($i === null) $i = $this->inputIndex - 1;
 186          else $i--;
 187          if ($i < 0) return false;
 188          $current = $this->inputTokens[$i];
 189          return true;
 190      }
 191  
 192      /**
 193       * Initializes the iterator at the current position. Use in a do {} while;
 194       * loop to force the _forward and _backward functions to start at the
 195       * current location.
 196       * @warning Please prevent previous references from interfering with this
 197       *          functions by setting $i = null beforehand!
 198       * @param &$i Current integer index variable for inputTokens
 199       * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
 200       */
 201      protected function current(&$i, &$current) {
 202          if ($i === null) $i = $this->inputIndex;
 203          $current = $this->inputTokens[$i];
 204      }
 205  
 206      /**
 207       * Handler that is called when a text token is processed
 208       */
 209      public function handleText(&$token) {}
 210  
 211      /**
 212       * Handler that is called when a start or empty token is processed
 213       */
 214      public function handleElement(&$token) {}
 215  
 216      /**
 217       * Handler that is called when an end token is processed
 218       */
 219      public function handleEnd(&$token) {
 220          $this->notifyEnd($token);
 221      }
 222  
 223      /**
 224       * Notifier that is called when an end token is processed
 225       * @note This differs from handlers in that the token is read-only
 226       * @deprecated
 227       */
 228      public function notifyEnd($token) {}
 229  
 230  
 231  }
 232  
 233  // vim: et sw=4 sts=4