Signatur
Beschreibung
CommonMark\Node\Document ist der Wurzelknoten (Root Node) des abstrakten Syntaxbaums (AST), der beim Parsen eines CommonMark-Dokuments entsteht. Alle anderen Knoten – wie Absätze, Überschriften, Listen oder Inline-Elemente – sind Kindknoten dieses Dokuments.
Die Klasse gehört zur PHP-Erweiterung commonmark (PECL) und wird typischerweise nicht direkt instanziiert, sondern als Rückgabewert von CommonMark\Parser::finish() erhalten. Das Document-Objekt kann anschließend mit einem CommonMark\Renderer in HTML oder andere Formate umgewandelt werden.
Als Unterklasse von CommonMark\Node erbt Document alle Methoden zum Traversieren und Manipulieren des Knotenbaums, etwa zum Hinzufügen, Entfernen oder Iterieren von Kindknoten. Dies erlaubt es, den AST vor dem Rendern programmatisch zu verändern.
- Über
$document->firstChild/$document->lastChildlassen sich die direkt enthaltenen Blöcke traversieren. - Mit
$document->walker()kann der gesamte Baum iteriert werden.
Beispiele
Markdown parsen und als HTML rendern
<?php
// Benötigt die PECL-Erweiterung 'commonmark'
$parser = new CommonMark\Parser();
$parser->write("# Hallo Welt\n\nDies ist ein **Absatz**.");
/** @var CommonMark\Node\Document $document */
$document = $parser->finish();
$renderer = new CommonMark\HtmlRenderer();
echo $renderer->renderDocument($document);AST traversieren und alle Überschriften ausgeben
<?php
$parser = new CommonMark\Parser();
$parser->write("# Kapitel 1\n\n## Abschnitt 1.1\n\nEtwas Text.\n\n# Kapitel 2");
$document = $parser->finish();
$walker = $document->walker();
while ($event = $walker->next()) {
$node = $event->getNode();
if ($node instanceof CommonMark\Node\Heading && $event->isEntering()) {
echo "H" . $node->level . ": ";
// Kindknoten für den Text ausgeben
$child = $node->firstChild;
while ($child) {
if ($child instanceof CommonMark\Node\Text) {
echo $child->literal;
}
$child = $child->next;
}
echo PHP_EOL;
}
}Document manuell aufbauen
<?php
// Dokument programmatisch erstellen
$document = new CommonMark\Node\Document();
$paragraph = new CommonMark\Node\Paragraph();
$text = new CommonMark\Node\Text();
$text->literal = 'Hallo, Welt!';
$paragraph->appendChild($text);
$document->appendChild($paragraph);
$renderer = new CommonMark\HtmlRenderer();
echo $renderer->renderDocument($document);// Wichtig · Fallstricke
PECL-Erweiterung erforderlich: Die Klasse ist Teil der PECL-Erweiterung commonmark und nicht im PHP-Kern enthalten. Sie muss separat installiert werden (pecl install commonmark). Für rein PHP-basierte CommonMark-Unterstützung gibt es Alternativen wie league/commonmark.
Da Document den gesamten AST hält, sollte bei sehr großen Markdown-Dokumenten auf den Speicherverbrauch geachtet werden. Der Walker iteriert den Baum tief-zuerst; Modifikationen am Baum während der Iteration können zu unvorhergesehenem Verhalten führen.