CommonMark\Node\Heading — Klasse · PHP-Referenz

Signatur

class CommonMark\Node\Heading extends CommonMark\Node

Beschreibung

CommonMark\Node\Heading ist ein Knoten-Typ innerhalb der league/commonmark-Bibliothek bzw. der CommonMark-PHP-Erweiterung. Er steht für eine ATX- oder Setext-Überschrift im geparsten Markdown-Dokument, also für Zeilen wie # Überschrift 1 bis ###### Überschrift 6.

Das wichtigste Attribut des Knotens ist level (Integer 1–6), das die Hierarchieebene der Überschrift beschreibt. Kinder-Knoten des Headings enthalten den eigentlichen Text (als Text- oder Inline-Knoten), sodass der vollständige Überschrifteninhalt über den Kinderbaum zugänglich ist.

Die Klasse wird typischerweise beim programmatischen Traversieren, Manipulieren oder Erstellen von CommonMark-Dokumentbäumen eingesetzt – zum Beispiel um alle Überschriften eines Dokuments zu extrahieren, Inhaltsverzeichnisse zu generieren oder Überschriftentexte zu transformieren.

Beim Lesen: Iteriere mit Node::walker() über den AST und prüfe Knoten auf instanceof CommonMark\Node\Heading.
Beim Erzeugen: Instanziiere Heading direkt, setze level und füge Text-Kinder hinzu, bevor du den Knoten in den Baum einhängst.

Parameter

Name	Typ	Default	Beschreibung
$level	int	1	Die Überschriftebene von `1` (H1) bis `6` (H6). Entspricht der Anzahl der `#`-Zeichen in ATX-Überschriften.

Rückgabewert

Typ

Beispiele

Alle Überschriften eines Dokuments auslesen

<?php
use CommonMark\Parser;
use CommonMark\Node\Heading;

$markdown = "# Kapitel 1\n\nText\n\n## Abschnitt 1.1\n\nWeiterer Text\n";

$parser   = new Parser();
$document = $parser->parse($markdown);

$walker = $document->walker();
while ($event = $walker->next()) {
    $node = $event->getNode();
    if ($event->isEntering() && $node instanceof Heading) {
        echo 'H' . $node->level . ': ' . $node->firstChild->literal . PHP_EOL;
    }
}

H1: Kapitel 1 H2: Abschnitt 1.1

Überschrift programmatisch erstellen und in Dokument einfügen

<?php
use CommonMark\Node\Document;
use CommonMark\Node\Heading;
use CommonMark\Node\Text;
use CommonMark\Render\HTML;

$document = new Document();

$heading = new Heading(2);
$text    = new Text();
$text->literal = 'Dynamische Überschrift';
$heading->appendChild($text);
$document->appendChild($heading);

$renderer = new HTML();
echo $renderer->renderDocument($document);

<h2>Dynamische Überschrift</h2>

Inhaltsverzeichnis aus Markdown generieren

<?php
use CommonMark\Parser;
use CommonMark\Node\Heading;
use CommonMark\Node\Text;

$markdown = "# Einleitung\n\n## Grundlagen\n\n### Details\n\n## Fazit\n";

$document = (new Parser())->parse($markdown);
$toc      = [];

$walker = $document->walker();
while ($event = $walker->next()) {
    $node = $event->getNode();
    if ($event->isEntering() && $node instanceof Heading) {
        $indent = str_repeat('  ', $node->level - 1);
        $label  = $node->firstChild instanceof Text ? $node->firstChild->literal : '(kein Text)';
        $toc[]  = $indent . '- ' . $label;
    }
}

echo implode(PHP_EOL, $toc);

- Einleitung - Grundlagen - Details - Fazit

// Wichtig · Fallstricke

Ebenen-Validierung: Werte für level außerhalb des Bereichs 1–6 können je nach Erweiterungsversion zu unerwartetem Verhalten oder Ausnahmen führen. Stelle sicher, nur gültige Werte zu setzen.

Kinder-Knoten: Der Textinhalt einer Überschrift ist nicht direkt im Heading-Objekt gespeichert, sondern in seinen Kind-Knoten (z. B. CommonMark\Node\Text). Ein direkter Zugriff auf $heading->literal liefert in der Regel null.

Abhängigkeit: Die Klasse ist Teil der cmark-PHP-Erweiterung (PECL) und steht nicht ohne Weiteres in Projekten zur Verfügung, die nur league/commonmark als Composer-Paket einbinden – dort heißt das Äquivalent League\CommonMark\Node\Block\Heading.

Siehe auch

CommonMark\Node CommonMark\Node\Document CommonMark\Node\Text CommonMark\Node\Paragraph CommonMark\Parser