CommonMark\Parser — Klasse · PHP-Referenz

Signatur

class CommonMark\Parser

Beschreibung

Die Klasse CommonMark\Parser ist Teil der PHP-Erweiterung commonmark (pecl/commonmark) und ermöglicht es, Markdown-Inhalte gemäß der CommonMark-Spezifikation zu verarbeiten. Das Ergebnis ist ein abstrakter Syntaxbaum (AST) aus CommonMark\Node-Objekten, der programmatisch traversiert, manipuliert und anschließend gerendert werden kann.

Im Gegensatz zu einer rein textbasierten HTML-Konvertierung bietet der AST-basierte Ansatz die Möglichkeit, einzelne Knoten (z. B. Überschriften, Codeblöcke oder Links) gezielt zu verändern, bevor das Dokument gerendert wird. Dies ist besonders nützlich für Anwendungen, die Markdown-Inhalte inhaltlich analysieren oder transformieren müssen.

Die typische Verwendung erfolgt in zwei Schritten: Zunächst wird der Parser instanziiert und Markdown-Text via parse() übergeben. Das zurückgegebene CommonMark\Node\Document-Objekt kann dann mit einem CommonMark\Renderer (z. B. CommonMark\Renderer\HTML) in HTML umgewandelt werden.

Die Erweiterung setzt eine PHP-Version ≥ 7.1 sowie die native libcmark-Bibliothek voraus. Für Standard-Konvertierungen ohne AST-Manipulation existiert die Hilfsfunktion CommonMark\convert(), die Parser und Renderer intern kombiniert.

Parameter

Name	Typ	Default	Beschreibung
$options	int	0	Optionales Bitmuster aus `CommonMark\Parser\*`-Konstanten, z. B. `CommonMark\Parser\NORMALIZE` oder `CommonMark\Parser\VALIDATE_UTF8`. Mehrere Flags werden per `\|` kombiniert.

Rückgabewert

Typ

Beispiele

Einfaches Parsen und Rendern von Markdown zu HTML

<?php

use CommonMark\Parser;
use CommonMark\Renderer\HTML;

$markdown = "# Willkommen\n\nDies ist ein **Beispiel** mit CommonMark.\n\n- Punkt 1\n- Punkt 2\n";

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

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

<h1>Willkommen</h1> <p>Dies ist ein <strong>Beispiel</strong> mit CommonMark.</p> <ul> <li>Punkt 1</li> <li>Punkt 2</li> </ul>

AST traversieren und Links einsammeln

<?php

use CommonMark\Parser;
use CommonMark\Node\Link;

$markdown = "Besuche [PHP.net](https://www.php.net) oder [PECL](https://pecl.php.net).\n";

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

$links = [];

// Rekursive Hilfsfunktion zum Traversieren des AST
function collectLinks($node, array &$links): void {
    if ($node instanceof Link) {
        $links[] = $node->url;
    }
    foreach ($node->children() ?? [] as $child) {
        collectLinks($child, $links);
    }
}

collectLinks($document, $links);

foreach ($links as $url) {
    echo $url . PHP_EOL;
}

https://www.php.net https://pecl.php.net

Parser mit UTF-8-Validierung und Normalisierung

<?php

use CommonMark\Parser;
use CommonMark\Renderer\HTML;

// Flags kombinieren
$options  = CommonMark\Parser\VALIDATE_UTF8 | CommonMark\Parser\NORMALIZE;
$parser   = new Parser($options);
$document = $parser->parse("## Überschrift\n\nMit Sonderzeichen: ä, ö, ü.\n");

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

<h2>Überschrift</h2> <p>Mit Sonderzeichen: ä, ö, ü.</p>

// Wichtig · Fallstricke

Sicherheitshinweis: Das Rendern von benutzergenerierten Markdown-Inhalten zu HTML birgt XSS-Risiken, da CommonMark Inline-HTML standardmäßig durchlässt. Aktiviere die Renderer-Option CommonMark\Renderer\HTML::SAFE (oder nutze CommonMark\Renderer\HTML::NO_HTML), um rohes HTML im Markdown zu unterdrücken, bevor du die Ausgabe im Browser anzeigst.

Die Methode parse() gibt bei leerem oder ungültigem Input ein leeres CommonMark\Node\Document zurück und wirft keine Exception — prüfe die Eingabe daher vorab, wenn eine leere Ausgabe kritisch ist.

Für einmalige Konvertierungen ohne AST-Manipulation empfiehlt sich die kürzere Hilfsfunktion CommonMark\convert(string $markdown, int $parserOptions, int $rendererOptions): string.

Siehe auch

CommonMark\Renderer\HTML CommonMark\Node\Document CommonMark\Node CommonMark\convert