]> git.mxchange.org Git - friendica.git/blob - library/HTMLPurifier/Injector.php
more friend suggestions
[friendica.git] / library / HTMLPurifier / Injector.php
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         // check for exclusion
141         for ($i = count($this->currentNesting) - 2; $i >= 0; $i--) {
142             $node = $this->currentNesting[$i];
143             $def  = $this->htmlDefinition->info[$node->name];
144             if (isset($def->excludes[$name])) return false;
145         }
146         return true;
147     }
148
149     /**
150      * Iterator function, which starts with the next token and continues until
151      * you reach the end of the input tokens.
152      * @warning Please prevent previous references from interfering with this
153      *          functions by setting $i = null beforehand!
154      * @param &$i Current integer index variable for inputTokens
155      * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
156      */
157     protected function forward(&$i, &$current) {
158         if ($i === null) $i = $this->inputIndex + 1;
159         else $i++;
160         if (!isset($this->inputTokens[$i])) return false;
161         $current = $this->inputTokens[$i];
162         return true;
163     }
164
165     /**
166      * Similar to _forward, but accepts a third parameter $nesting (which
167      * should be initialized at 0) and stops when we hit the end tag
168      * for the node $this->inputIndex starts in.
169      */
170     protected function forwardUntilEndToken(&$i, &$current, &$nesting) {
171         $result = $this->forward($i, $current);
172         if (!$result) return false;
173         if ($nesting === null) $nesting = 0;
174         if     ($current instanceof HTMLPurifier_Token_Start) $nesting++;
175         elseif ($current instanceof HTMLPurifier_Token_End) {
176             if ($nesting <= 0) return false;
177             $nesting--;
178         }
179         return true;
180     }
181
182     /**
183      * Iterator function, starts with the previous token and continues until
184      * you reach the beginning of input tokens.
185      * @warning Please prevent previous references from interfering with this
186      *          functions by setting $i = null beforehand!
187      * @param &$i Current integer index variable for inputTokens
188      * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
189      */
190     protected function backward(&$i, &$current) {
191         if ($i === null) $i = $this->inputIndex - 1;
192         else $i--;
193         if ($i < 0) return false;
194         $current = $this->inputTokens[$i];
195         return true;
196     }
197
198     /**
199      * Initializes the iterator at the current position. Use in a do {} while;
200      * loop to force the _forward and _backward functions to start at the
201      * current location.
202      * @warning Please prevent previous references from interfering with this
203      *          functions by setting $i = null beforehand!
204      * @param &$i Current integer index variable for inputTokens
205      * @param &$current Current token variable. Do NOT use $token, as that variable is also a reference
206      */
207     protected function current(&$i, &$current) {
208         if ($i === null) $i = $this->inputIndex;
209         $current = $this->inputTokens[$i];
210     }
211
212     /**
213      * Handler that is called when a text token is processed
214      */
215     public function handleText(&$token) {}
216
217     /**
218      * Handler that is called when a start or empty token is processed
219      */
220     public function handleElement(&$token) {}
221
222     /**
223      * Handler that is called when an end token is processed
224      */
225     public function handleEnd(&$token) {
226         $this->notifyEnd($token);
227     }
228
229     /**
230      * Notifier that is called when an end token is processed
231      * @note This differs from handlers in that the token is read-only
232      * @deprecated
233      */
234     public function notifyEnd($token) {}
235
236
237 }
238
239 // vim: et sw=4 sts=4