Dom\DocumentFragment — Klasse · PHP-Referenz

Signatur

class Dom\DocumentFragment extends Dom\Node implements Dom\ParentNode

Beschreibung

Dom\DocumentFragment ist ein spezieller Knotentyp der modernen PHP-DOM-Erweiterung (Namespace Dom\, eingeführt in PHP 8.4). Er dient als temporärer Container für DOM-Knoten, der selbst kein echtes Element im Dokument darstellt. Wird ein Fragment in den Dokumentbaum eingefügt, werden nur seine Kinder – nicht das Fragment selbst – eingefügt. Dadurch lassen sich mehrere Knoten mit einem einzigen Einfügevorgang effizient hinzufügen.

Ein typischer Anwendungsfall ist das Aufbauen größerer DOM-Strukturen außerhalb des Hauptbaums, um teure Reflows und Re-Renderings zu minimieren. Sobald das Fragment fertig aufgebaut ist, wird es per appendChild() oder insertBefore() an den gewünschten Elternknoten angehängt.

Instanzen werden nicht direkt erzeugt, sondern über die Fabrikmethode Dom\Document::createDocumentFragment(). Die Klasse implementiert Dom\ParentNode und unterstützt daher Methoden wie append(), prepend() sowie die Eigenschaft children für den direkten Zugriff auf Element-Kindknoten.

Hinweis: Diese Klasse gehört zur neuen, spezifikationskonformen Dom\-Hierarchie und ist nicht zu verwechseln mit dem älteren DOMDocumentFragment aus der klassischen ext/dom-Erweiterung, die seit PHP 5 existiert.

Beispiele

Mehrere Knoten per Fragment effizient einfügen

<?php
$doc = Dom\XMLDocument::createFromString('<root><list/></root>');
$list = $doc->querySelector('list');

$fragment = $doc->createDocumentFragment();

foreach (['Eins', 'Zwei', 'Drei'] as $text) {
    $item = $doc->createElement('item');
    $item->textContent = $text;
    $fragment->appendChild($item);
}

// Alle Kinder des Fragments werden auf einmal eingefügt
$list->appendChild($fragment);

echo $doc->saveXml();

<?xml version="1.0" encoding="UTF-8"?> <root><list><item>Eins</item><item>Zwei</item><item>Drei</item></list></root>

HTML-Markup per appendXml() in ein Fragment parsen

<?php
$doc = Dom\HTMLDocument::createFromString('<body><section id="main"></section></body>', LIBXML_NOERROR);
$section = $doc->getElementById('main');

$fragment = $doc->createDocumentFragment();
// appendXml() parst eine XML/HTML-Zeichenkette direkt in das Fragment
$fragment->appendXml('<p>Erster Absatz</p><p>Zweiter Absatz</p>');

$section->appendChild($fragment);

echo $doc->saveHtml($section);

<section id="main"><p>Erster Absatz</p><p>Zweiter Absatz</p></section>

// Wichtig · Fallstricke

Nicht mit DOMDocumentFragment verwechseln: Die ältere Klasse DOMDocumentFragment im globalen Namespace (seit PHP 5) ist eine separate Klasse. Dom\DocumentFragment folgt dem WHATWG/W3C-DOM-Standard strenger und ist nur über Dokumente aus der neuen Dom\-Hierarchie (Dom\HTMLDocument, Dom\XMLDocument) verfügbar.

Nach dem Einfügen eines Fragments in den Dokumentbaum ist das Fragment leer – seine Kindknoten wurden in den Zielknoten verschoben. Das Fragment-Objekt kann danach wiederverwendet werden, enthält dann aber keine Knoten mehr.

Bei der Verwendung von appendXml() muss der übergebene String wohlgeformtes XML sein; ungültige Fragmente führen zu einem Fehler.

Siehe auch

Dom\Document::createDocumentFragment DOMDocumentFragment Dom\Document Dom\Node Dom\ParentNode Dom\HTMLDocument Dom\XMLDocument