Signatur
Beschreibung
CommonMark\Node ist die abstrakte Basisklasse der CommonMark-PHP-Erweiterung und repräsentiert einen einzelnen Knoten im abstrakten Syntaxbaum (AST), der beim Verarbeiten von Markdown-Dokumenten aufgebaut wird. Jedes Markdown-Element – Absätze, Überschriften, Listen, Links, Code-Blöcke usw. – wird als spezialisierte Unterklasse von CommonMark\Node abgebildet.
Die Klasse stellt gemeinsame Eigenschaften und Methoden zur Verfügung, über die alle Knoten verfügen: Navigation im Baum (Elternknoten, Kindknoten, Geschwisterknoten), Manipulation der Baumstruktur sowie den Zugriff auf den Rohinhalt des Knotens. Damit bildet sie das Fundament für das Traversieren und die Transformation von AST-Bäumen.
Typische Anwendungsfälle sind das Einlesen eines Markdown-Textes mit CommonMark\Parser, das anschließende Traversieren des resultierenden Baums sowie das gezielte Hinzufügen, Entfernen oder Ersetzen von Knoten, bevor der Baum mit CommonMark\Renderer wieder in HTML oder ein anderes Format überführt wird.
Da CommonMark\Node selbst nicht instanziiert werden soll, arbeitet man in der Praxis stets mit konkreten Unterklassen wie CommonMark\Node\Document, CommonMark\Node\Paragraph, CommonMark\Node\Heading und ähnlichen.
Beispiele
Markdown parsen und Knotentypen im AST ausgeben
<?php
// CommonMark-Erweiterung muss installiert sein (pecl install commonmark)
$parser = new CommonMark\Parser();
$parser->parse("# Überschrift\n\nEin **fetter** Absatz.\n");
$document = $parser->finish();
// Rekursive Funktion zum Traversieren des Baums
function traverseNode(CommonMark\Node $node, int $depth = 0): void {
echo str_repeat(' ', $depth) . get_class($node);
if ($node->literal !== null) {
echo ' [' . addslashes($node->literal) . ']';
}
echo PHP_EOL;
// Kindknoten durchlaufen
$child = $node->firstChild;
while ($child !== null) {
traverseNode($child, $depth + 1);
$child = $child->next;
}
}
traverseNode($document);Knoten aus dem AST entfernen und Dokument neu rendern
<?php
$parser = new CommonMark\Parser();
$parser->parse("# Titel\n\nErster Absatz.\n\nZweiter Absatz.\n");
$document = $parser->finish();
// Alle Überschriften aus dem Dokument entfernen
function removeHeadings(CommonMark\Node $node): void {
$child = $node->firstChild;
while ($child !== null) {
$next = $child->next;
if ($child instanceof CommonMark\Node\Heading) {
$child->unlink(); // Knoten aus dem Baum herauslösen
} else {
removeHeadings($child);
}
$child = $next;
}
}
removeHeadings($document);
$renderer = new CommonMark\Renderer\HTML();
echo $renderer->render($document);// Wichtig · Fallstricke
Erweiterung erforderlich: CommonMark\Node ist Teil der PHP-Erweiterung commonmark, die über PECL installiert werden muss (pecl install commonmark). Sie ist nicht Bestandteil der PHP-Standardbibliothek.
Direkte Instanziierung: CommonMark\Node selbst kann nicht direkt instanziiert werden. Verwende stets eine der konkreten Unterklassen (z.B. CommonMark\Node\Paragraph, CommonMark\Node\Text).
Baum-Manipulation: Beim Traversieren und gleichzeitigen Entfernen von Knoten immer den next-Zeiger vor dem Aufruf von unlink() sichern, da sonst die Verkettung verloren geht und Knoten übersprungen werden können.
Inhalt von Knoten: Nicht jeder Knotentyp besitzt ein literal-Attribut mit Text. Prüfe vor dem Zugriff, ob der Wert nicht null ist, um Fehler zu vermeiden.