Commit | Line | Data |
---|---|---|
60a35505 | 1 | <?php |
a9229942 | 2 | |
60a35505 | 3 | namespace wcf\util; |
a9229942 | 4 | |
df0d9cf6 | 5 | use wcf\system\exception\SystemException; |
60a35505 AE |
6 | |
7 | /** | |
8 | * Provides helper methods to work with PHP's DOM implementation. | |
a9229942 TD |
9 | * |
10 | * @author Alexander Ebert | |
11 | * @copyright 2001-2019 WoltLab GmbH | |
12 | * @license GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php> | |
13 | * @package WoltLabSuite\Core\Util | |
60a35505 | 14 | */ |
a9229942 TD |
15 | final class DOMUtil |
16 | { | |
17 | /** | |
18 | * Moves all child nodes from given element into a document fragment. | |
19 | * | |
20 | * @param \DOMElement $element element | |
21 | * @return \DOMDocumentFragment document fragment containing all child nodes from `$element` | |
22 | */ | |
23 | public static function childNodesToFragment(\DOMElement $element) | |
24 | { | |
25 | $fragment = $element->ownerDocument->createDocumentFragment(); | |
26 | ||
27 | while ($element->hasChildNodes()) { | |
28 | $fragment->appendChild($element->childNodes->item(0)); | |
29 | } | |
30 | ||
31 | return $fragment; | |
32 | } | |
33 | ||
34 | /** | |
35 | * Returns true if `$ancestor` contains the node `$node`. | |
36 | * | |
37 | * @param \DOMNode $ancestor ancestor node | |
38 | * @param \DOMNode $node node | |
39 | * @return bool true if `$ancestor` contains the node `$node` | |
40 | */ | |
41 | public static function contains(\DOMNode $ancestor, \DOMNode $node) | |
42 | { | |
43 | // nodes cannot contain themselves | |
44 | if ($ancestor === $node) { | |
45 | return false; | |
46 | } | |
47 | ||
48 | // text nodes cannot contain any other nodes | |
49 | if ($ancestor->nodeType === \XML_TEXT_NODE) { | |
50 | return false; | |
51 | } | |
52 | ||
53 | $parent = $node; | |
54 | while ($parent = $parent->parentNode) { | |
55 | if ($parent === $ancestor) { | |
56 | return true; | |
57 | } | |
58 | } | |
59 | ||
60 | return false; | |
61 | } | |
62 | ||
63 | /** | |
64 | * Returns a static list of child nodes of provided element. | |
65 | * | |
66 | * @param \DOMElement $element target element | |
67 | * @return \DOMNode[] list of child nodes | |
68 | */ | |
69 | public static function getChildNodes(\DOMElement $element) | |
70 | { | |
71 | $nodes = []; | |
72 | foreach ($element->childNodes as $node) { | |
73 | $nodes[] = $node; | |
74 | } | |
75 | ||
76 | return $nodes; | |
77 | } | |
78 | ||
79 | /** | |
80 | * Returns the common ancestor of both nodes. | |
81 | * | |
82 | * @param \DOMNode $node1 first node | |
83 | * @param \DOMNode $node2 second node | |
84 | * @return \DOMNode|null common ancestor or null | |
85 | */ | |
86 | public static function getCommonAncestor(\DOMNode $node1, \DOMNode $node2) | |
87 | { | |
88 | // abort if both elements share a common element or are both direct descendants | |
89 | // of the same document | |
90 | if ($node1->parentNode === $node2->parentNode) { | |
91 | return $node1->parentNode; | |
92 | } | |
93 | ||
94 | // collect the list of all direct ancestors of `$node1` | |
95 | $parents = self::getParents($node1); | |
96 | ||
97 | // compare each ancestor of `$node2` to the known list of parents of `$node1` | |
98 | $parent = $node2; | |
99 | while ($parent = $parent->parentNode) { | |
100 | // requires strict type check | |
101 | if (\in_array($parent, $parents, true)) { | |
102 | return $parent; | |
103 | } | |
104 | } | |
5227ebc7 MS |
105 | |
106 | return null; | |
a9229942 TD |
107 | } |
108 | ||
109 | /** | |
110 | * Returns a non-live collection of elements. | |
111 | * | |
112 | * @param (\DOMDocument|\DOMElement) $context context element | |
113 | * @param string $tagName tag name | |
114 | * @return \DOMElement[] list of elements | |
115 | * @throws SystemException | |
116 | */ | |
117 | public static function getElements($context, $tagName) | |
118 | { | |
119 | if (!($context instanceof \DOMDocument) && !($context instanceof \DOMElement)) { | |
120 | throw new SystemException("Expected context to be either of type \\DOMDocument or \\DOMElement."); | |
121 | } | |
122 | ||
123 | $elements = []; | |
124 | foreach ($context->getElementsByTagName($tagName) as $element) { | |
125 | $elements[] = $element; | |
126 | } | |
127 | ||
128 | return $elements; | |
129 | } | |
130 | ||
131 | /** | |
132 | * Returns the immediate parent element before provided ancestor element. Returns null if | |
133 | * the ancestor element is the direct parent of provided node. | |
134 | * | |
135 | * @param \DOMNode $node node | |
136 | * @param \DOMElement $ancestor ancestor node | |
137 | * @return \DOMElement|null immediate parent element before ancestor element | |
138 | */ | |
139 | public static function getParentBefore(\DOMNode $node, \DOMElement $ancestor) | |
140 | { | |
141 | if ($node->parentNode === $ancestor) { | |
c0b28aa2 | 142 | return null; |
a9229942 TD |
143 | } |
144 | ||
145 | $parents = self::getParents($node); | |
146 | for ($i = \count($parents) - 1; $i >= 0; $i--) { | |
147 | if ($parents[$i] === $ancestor) { | |
148 | return $parents[$i - 1]; | |
149 | } | |
150 | } | |
151 | ||
152 | throw new \InvalidArgumentException("Provided node is a not a descendant of ancestor element."); | |
153 | } | |
154 | ||
155 | /** | |
156 | * Returns the parent node of given node. | |
157 | * | |
158 | * @param \DOMNode $node node | |
159 | * @return \DOMNode parent node, can be `\DOMElement` or `\DOMDocument` | |
160 | */ | |
161 | public static function getParentNode(\DOMNode $node) | |
162 | { | |
163 | return $node->parentNode ?: $node->ownerDocument; | |
164 | } | |
165 | ||
166 | /** | |
167 | * Returns all ancestors nodes for given node. | |
168 | * | |
169 | * @param \DOMNode $node node | |
170 | * @param bool $reverseOrder reversing the order causes the most top ancestor to appear first | |
171 | * @return \DOMElement[] list of ancestor nodes | |
172 | */ | |
173 | public static function getParents(\DOMNode $node, $reverseOrder = false) | |
174 | { | |
175 | $parents = []; | |
176 | ||
177 | $parent = $node; | |
178 | while ($parent = $parent->parentNode) { | |
179 | $parents[] = $parent; | |
180 | } | |
181 | ||
182 | return $reverseOrder ? \array_reverse($parents) : $parents; | |
183 | } | |
184 | ||
185 | /** | |
186 | * Returns a cloned parent tree that is virtually readonly. In fact it can be | |
187 | * modified, but all changes are non permanent and do not affect the source | |
188 | * document at all. | |
189 | * | |
190 | * @param \DOMNode $node node | |
191 | * @return \DOMElement[] list of parent elements | |
192 | */ | |
193 | public static function getReadonlyParentTree(\DOMNode $node) | |
194 | { | |
195 | $tree = []; | |
196 | /** @var \DOMElement $parent */ | |
197 | foreach (self::getParents($node) as $parent) { | |
198 | // do not include <body>, <html> and the document itself | |
199 | if ($parent->nodeName === 'body') { | |
200 | break; | |
201 | } | |
202 | ||
203 | $tree[] = $parent->cloneNode(false); | |
204 | } | |
205 | ||
206 | return $tree; | |
207 | } | |
208 | ||
209 | /** | |
210 | * Determines the relative position of two nodes to each other. | |
211 | * | |
212 | * @param \DOMNode $node1 first node | |
213 | * @param \DOMNode $node2 second node | |
214 | * @return string | |
215 | */ | |
216 | public static function getRelativePosition(\DOMNode $node1, \DOMNode $node2) | |
217 | { | |
218 | if ($node1->ownerDocument !== $node2->ownerDocument) { | |
219 | throw new \InvalidArgumentException("Both nodes must be contained in the same DOM document."); | |
220 | } | |
221 | ||
222 | $nodeList1 = self::getParents($node1, true); | |
223 | $nodeList1[] = $node1; | |
224 | ||
225 | $nodeList2 = self::getParents($node2, true); | |
226 | $nodeList2[] = $node2; | |
227 | ||
228 | $i = 0; | |
229 | while ($nodeList1[$i] === $nodeList2[$i]) { | |
230 | $i++; | |
231 | } | |
232 | ||
233 | // check if parent of node 2 appears before parent of node 1 | |
234 | $previousSibling = $nodeList1[$i]; | |
235 | while ($previousSibling = $previousSibling->previousSibling) { | |
236 | if ($previousSibling === $nodeList2[$i]) { | |
237 | return 'before'; | |
238 | } | |
239 | } | |
240 | ||
241 | $nextSibling = $nodeList1[$i]; | |
242 | while ($nextSibling = $nextSibling->nextSibling) { | |
243 | if ($nextSibling === $nodeList2[$i]) { | |
244 | return 'after'; | |
245 | } | |
246 | } | |
247 | ||
248 | throw new \RuntimeException("Unable to determine relative node position."); | |
249 | } | |
250 | ||
251 | /** | |
252 | * Returns true if there is at least one parent with the provided tag name. | |
253 | * | |
254 | * @param \DOMElement $element start element | |
255 | * @param string $tagName tag name to match | |
256 | * @return bool | |
257 | */ | |
258 | public static function hasParent(\DOMElement $element, $tagName) | |
259 | { | |
260 | while ($element = $element->parentNode) { | |
261 | if ($element->nodeName === $tagName) { | |
262 | return true; | |
263 | } | |
264 | } | |
265 | ||
266 | return false; | |
267 | } | |
268 | ||
269 | /** | |
270 | * Inserts given DOM node after the reference node. | |
271 | * | |
272 | * @param \DOMNode $node node | |
273 | * @param \DOMNode $refNode reference node | |
274 | */ | |
275 | public static function insertAfter(\DOMNode $node, \DOMNode $refNode) | |
276 | { | |
277 | if ($refNode->nextSibling) { | |
278 | self::insertBefore($node, $refNode->nextSibling); | |
279 | } else { | |
280 | self::getParentNode($refNode)->appendChild($node); | |
281 | } | |
282 | } | |
283 | ||
284 | /** | |
285 | * Inserts given node before the reference node. | |
286 | * | |
287 | * @param \DOMNode $node node | |
288 | * @param \DOMNode $refNode reference node | |
289 | */ | |
290 | public static function insertBefore(\DOMNode $node, \DOMNode $refNode) | |
291 | { | |
292 | self::getParentNode($refNode)->insertBefore($node, $refNode); | |
293 | } | |
294 | ||
295 | /** | |
296 | * Returns true if this node is empty. | |
297 | * | |
298 | * @param \DOMNode $node node | |
299 | * @return bool true if node is empty | |
300 | */ | |
301 | public static function isEmpty(\DOMNode $node) | |
302 | { | |
303 | if ($node->nodeType === \XML_TEXT_NODE) { | |
304 | return StringUtil::trim($node->nodeValue) === ''; | |
305 | } elseif ($node->nodeType === \XML_ELEMENT_NODE) { | |
306 | /** @var \DOMElement $node */ | |
307 | if (self::isVoidElement($node)) { | |
308 | return false; | |
309 | } elseif ($node->hasChildNodes()) { | |
310 | for ($i = 0, $length = $node->childNodes->length; $i < $length; $i++) { | |
311 | if (!self::isEmpty($node->childNodes->item($i))) { | |
312 | return false; | |
313 | } | |
314 | } | |
315 | } | |
316 | ||
317 | return true; | |
318 | } | |
319 | ||
320 | return true; | |
321 | } | |
322 | ||
323 | /** | |
324 | * Returns true if given node is the first node of its given ancestor. | |
325 | * | |
326 | * @param \DOMNode $node node | |
327 | * @param \DOMElement $ancestor ancestor element | |
328 | * @return bool true if `$node` is the first node of its given ancestor | |
329 | */ | |
330 | public static function isFirstNode(\DOMNode $node, \DOMElement $ancestor) | |
331 | { | |
332 | if ($node->previousSibling === null) { | |
333 | if ($node->parentNode === $ancestor || $node->parentNode->nodeName === 'body') { | |
334 | return true; | |
335 | } else { | |
336 | return self::isFirstNode($node->parentNode, $ancestor); | |
337 | } | |
338 | } elseif ($node->parentNode->nodeName === 'body') { | |
339 | return true; | |
340 | } | |
341 | ||
342 | return false; | |
343 | } | |
344 | ||
345 | /** | |
346 | * Returns true if given node is the last node of its given ancestor. | |
347 | * | |
348 | * @param \DOMNode $node node | |
349 | * @param \DOMElement $ancestor ancestor element | |
350 | * @return bool true if `$node` is the last node of its given ancestor | |
351 | */ | |
352 | public static function isLastNode(\DOMNode $node, \DOMElement $ancestor) | |
353 | { | |
354 | if ($node->nextSibling === null) { | |
355 | if ($node->parentNode === null) { | |
356 | throw new \InvalidArgumentException("Provided node is a not a descendant of ancestor element."); | |
357 | } elseif ($node->parentNode === $ancestor || $node->parentNode->nodeName === 'body') { | |
358 | return true; | |
359 | } else { | |
360 | return self::isLastNode($node->parentNode, $ancestor); | |
361 | } | |
362 | } elseif ($node->parentNode->nodeName === 'body') { | |
363 | return true; | |
364 | } | |
365 | ||
366 | return false; | |
367 | } | |
368 | ||
369 | /** | |
370 | * Nodes can get partially destroyed in which they're still an | |
371 | * actual DOM node (such as \DOMElement) but almost their entire | |
372 | * body is gone, including the `nodeType` attribute. | |
373 | * | |
374 | * @param \DOMNode $node node | |
375 | * @return bool true if node has been destroyed | |
376 | */ | |
377 | public static function isRemoved(\DOMNode $node) | |
378 | { | |
379 | return !isset($node->nodeType); | |
380 | } | |
381 | ||
382 | /** | |
383 | * Returns true if provided element is a void element. Void elements are elements | |
384 | * that neither contain content nor have a closing tag, such as `<br>`. | |
385 | * | |
386 | * @param \DOMElement $element element | |
387 | * @return bool true if provided element is a void element | |
388 | */ | |
389 | public static function isVoidElement(\DOMElement $element) | |
390 | { | |
391 | if ( | |
392 | \preg_match( | |
393 | '~^(area|base|br|col|embed|hr|img|input|keygen|link|menuitem|meta|param|source|track|wbr)$~', | |
394 | $element->nodeName | |
395 | ) | |
396 | ) { | |
397 | return true; | |
398 | } | |
399 | ||
400 | return false; | |
401 | } | |
402 | ||
403 | /** | |
404 | * Moves all nodes into `$container` until it reaches `$lastElement`. The direction | |
405 | * in which nodes will be considered for moving is determined by the logical position | |
406 | * of `$lastElement`. | |
407 | * | |
408 | * @param \DOMElement $container destination element | |
409 | * @param \DOMElement $lastElement last element to move | |
410 | * @param \DOMElement $commonAncestor common ancestor of `$container` and `$lastElement` | |
411 | */ | |
412 | public static function moveNodesInto(\DOMElement $container, \DOMElement $lastElement, \DOMElement $commonAncestor) | |
413 | { | |
414 | if (!self::contains($commonAncestor, $container)) { | |
415 | throw new \InvalidArgumentException( | |
416 | "The container element must be a child of the common ancestor element." | |
417 | ); | |
418 | } elseif ($lastElement->parentNode !== $commonAncestor) { | |
419 | throw new \InvalidArgumentException( | |
420 | "The last element must be a direct child of the common ancestor element." | |
421 | ); | |
422 | } | |
423 | ||
424 | $relativePosition = self::getRelativePosition($container, $lastElement); | |
425 | ||
426 | // move everything that is logically after `$container` but within | |
427 | // `$commonAncestor` into `$container` until `$lastElement` has been moved | |
428 | $element = $container; | |
429 | do { | |
430 | if ($relativePosition === 'before') { | |
431 | while ($sibling = $element->previousSibling) { | |
432 | self::prepend($sibling, $container); | |
433 | if ($sibling === $lastElement) { | |
434 | return; | |
435 | } | |
436 | } | |
437 | } else { | |
438 | while ($sibling = $element->nextSibling) { | |
439 | $container->appendChild($sibling); | |
440 | if ($sibling === $lastElement) { | |
441 | return; | |
442 | } | |
443 | } | |
444 | } | |
445 | ||
446 | $element = $element->parentNode; | |
447 | } while ($element !== $commonAncestor); | |
448 | } | |
449 | ||
450 | /** | |
451 | * Normalizes an element by joining adjacent text nodes. | |
452 | * | |
453 | * @param \DOMElement $element target element | |
454 | */ | |
455 | public static function normalize(\DOMElement $element) | |
456 | { | |
457 | $childNodes = self::getChildNodes($element); | |
458 | /** @var \DOMNode $lastTextNode */ | |
459 | $lastTextNode = null; | |
460 | foreach ($childNodes as $childNode) { | |
461 | if ($childNode->nodeType !== \XML_TEXT_NODE) { | |
462 | $lastTextNode = null; | |
463 | continue; | |
464 | } | |
465 | ||
466 | if ($lastTextNode === null) { | |
467 | $lastTextNode = $childNode; | |
468 | } else { | |
469 | // merge with last text node | |
470 | $newTextNode = $childNode | |
471 | ->ownerDocument | |
472 | ->createTextNode($lastTextNode->textContent . $childNode->textContent); | |
473 | $element->insertBefore($newTextNode, $lastTextNode); | |
474 | ||
475 | $element->removeChild($lastTextNode); | |
476 | $element->removeChild($childNode); | |
477 | ||
478 | $lastTextNode = $newTextNode; | |
479 | } | |
480 | } | |
481 | } | |
482 | ||
483 | /** | |
484 | * Prepends a node to provided element. | |
485 | * | |
486 | * @param \DOMNode $node node | |
487 | * @param \DOMElement $element target element | |
488 | */ | |
489 | public static function prepend(\DOMNode $node, \DOMElement $element) | |
490 | { | |
491 | if ($element->firstChild === null) { | |
492 | $element->appendChild($node); | |
493 | } else { | |
494 | $element->insertBefore($node, $element->firstChild); | |
495 | } | |
496 | } | |
497 | ||
498 | /** | |
499 | * Removes a node, optionally preserves the child nodes if `$node` is an element. | |
500 | * | |
501 | * @param \DOMNode $node target node | |
502 | * @param bool $preserveChildNodes preserve child nodes, only supported for elements | |
503 | */ | |
504 | public static function removeNode(\DOMNode $node, $preserveChildNodes = false) | |
505 | { | |
c23f877c | 506 | $parent = $node->parentNode ?: $node->ownerDocument; |
c14276ab | 507 | |
a9229942 TD |
508 | if ($preserveChildNodes) { |
509 | if (!($node instanceof \DOMElement)) { | |
510 | throw new \InvalidArgumentException("Preserving child nodes is only supported for DOMElement."); | |
511 | } | |
512 | ||
c23f877c MS |
513 | $children = []; |
514 | foreach ($node->childNodes as $childNode) { | |
515 | $children[] = $childNode; | |
516 | } | |
517 | ||
518 | foreach ($children as $child) { | |
519 | $parent->insertBefore($child, $node); | |
a9229942 TD |
520 | } |
521 | } | |
522 | ||
c23f877c | 523 | $parent->removeChild($node); |
a9229942 TD |
524 | } |
525 | ||
526 | /** | |
527 | * Replaces a DOM element with another, preserving all child nodes by default. | |
528 | * | |
529 | * @param \DOMElement $oldElement old element | |
530 | * @param \DOMElement $newElement new element | |
531 | * @param bool $preserveChildNodes true if child nodes should be moved, otherwise they'll be implicitly removed | |
532 | */ | |
533 | public static function replaceElement(\DOMElement $oldElement, \DOMElement $newElement, $preserveChildNodes = true) | |
534 | { | |
535 | self::insertBefore($newElement, $oldElement); | |
536 | ||
537 | // move all child nodes | |
538 | if ($preserveChildNodes) { | |
539 | while ($oldElement->hasChildNodes()) { | |
540 | $newElement->appendChild($oldElement->childNodes->item(0)); | |
541 | } | |
542 | } | |
543 | ||
544 | // remove old element | |
545 | self::getParentNode($oldElement)->removeChild($oldElement); | |
546 | } | |
547 | ||
548 | /** | |
549 | * Splits all parent nodes until `$ancestor` and moved other nodes after/before | |
550 | * (determined by `$splitBefore`) into the newly created nodes. This allows | |
551 | * extraction of DOM parts while preserving nesting for both the extracted nodes | |
552 | * and the remaining siblings. | |
553 | * | |
554 | * @param \DOMNode $node reference node | |
555 | * @param \DOMElement $ancestor ancestor element that should not be split | |
556 | * @param bool $splitBefore true if nodes before `$node` should be moved into a new node, false to split nodes after `$node` | |
557 | * @return \DOMNode parent node containing `$node`, direct child of `$ancestor` | |
558 | */ | |
559 | public static function splitParentsUntil(\DOMNode $node, \DOMElement $ancestor, $splitBefore = true) | |
560 | { | |
561 | if (!self::contains($ancestor, $node)) { | |
562 | throw new \InvalidArgumentException("Node is not contained in ancestor node."); | |
563 | } | |
564 | ||
565 | // clone the parent node right "below" `$ancestor` | |
566 | $cloneNode = self::getParentBefore($node, $ancestor); | |
567 | ||
568 | if ($splitBefore) { | |
569 | if ($cloneNode === null) { | |
570 | // target node is already a direct descendant of the ancestor | |
571 | // node, no need to split anything | |
572 | return $node; | |
573 | } elseif (self::isFirstNode($node, $cloneNode)) { | |
574 | // target node is at the very start, we can safely move the | |
575 | // entire parent node around | |
576 | return $cloneNode; | |
577 | } | |
578 | ||
579 | $currentNode = $node; | |
580 | while (($parent = $currentNode->parentNode) !== $ancestor) { | |
581 | /** @var \DOMElement $newNode */ | |
582 | $newNode = $parent->cloneNode(); | |
583 | self::insertBefore($newNode, $parent); | |
584 | ||
585 | while ($currentNode->previousSibling) { | |
586 | self::prepend($currentNode->previousSibling, $newNode); | |
587 | } | |
588 | ||
589 | $currentNode = $parent; | |
590 | } | |
591 | } else { | |
592 | if ($cloneNode === null) { | |
593 | // target node is already a direct descendant of the ancestor | |
594 | // node, no need to split anything | |
595 | return $node; | |
596 | } elseif (self::isLastNode($node, $cloneNode)) { | |
597 | // target node is at the very end, we can safely move the | |
598 | // entire parent node around | |
599 | return $cloneNode; | |
600 | } | |
601 | ||
602 | $currentNode = $node; | |
603 | while (($parent = $currentNode->parentNode) !== $ancestor) { | |
604 | $newNode = $parent->cloneNode(); | |
605 | self::insertAfter($newNode, $parent); | |
606 | ||
607 | while ($currentNode->nextSibling) { | |
608 | $newNode->appendChild($currentNode->nextSibling); | |
609 | } | |
610 | ||
611 | $currentNode = $parent; | |
612 | } | |
613 | } | |
614 | ||
615 | return self::getParentBefore($node, $ancestor); | |
616 | } | |
617 | ||
618 | /** | |
619 | * Forbid creation of DOMUtil objects. | |
620 | */ | |
621 | private function __construct() | |
622 | { | |
623 | // does nothing | |
624 | } | |
60a35505 | 625 | } |