CommonMark\Parse — Funktion · PHP-Referenz

Signatur

CommonMark\Parse(string $content, int $options = 0): CommonMark\Node\Document

Beschreibung

CommonMark\Parse ist die zentrale Parsing-Funktion der PHP-Erweiterung commonmark (PECL). Sie wandelt einen im CommonMark-Standard formatierten Markdown-Text in einen abstrakten Syntaxbaum (AST) um, der als CommonMark\Node\Document-Objekt repräsentiert wird.

Das resultierende Dokument-Objekt kann anschließend programmatisch traversiert und manipuliert werden – etwa, um einzelne Knoten (Überschriften, Links, Absätze usw.) zu verändern, zu entfernen oder hinzuzufügen, bevor der AST schließlich mit CommonMark\Render\HTML oder einer ähnlichen Render-Funktion in HTML umgewandelt wird.

Über den optionalen Parameter $options lassen sich verschiedene Parser-Einstellungen aktivieren, beispielsweise das Erlauben von unsicherem HTML (CommonMark\Parser\UNSAFE_LINKS) oder das Aktivieren von GitHub-Flavored-Markdown-Erweiterungen. Die möglichen Flags können per bitweisem |-Operator kombiniert werden.

Die Funktion ist besonders nützlich, wenn man nicht nur eine einfache Markdown-zu-HTML-Konvertierung benötigt, sondern den Inhalt vorher analysieren oder transformieren möchte.

Parameter

Name	Typ	Default	Beschreibung
$content Pflicht	string		Der zu parsende CommonMark/Markdown-Text als UTF-8-kodierter String.
$options	int	0	Bitmaske aus Parser-Optionen (z. B. `CommonMark\Parser\NORMAL`, `CommonMark\Parser\UNSAFE_LINKS`). Standardmäßig keine besonderen Optionen gesetzt.

Rückgabewert

Typ

CommonMark\Node\Document

Beschreibung

Gibt ein CommonMark\Node\Document-Objekt zurück, das den abstrakten Syntaxbaum (AST) des geparsten Dokuments darstellt. Wirft eine CommonMark\Exception, wenn das Parsing fehlschlägt.

Beispiele

Einfaches Parsen und Rendern als HTML

<?php
$markdown = "# Hallo Welt\n\nDies ist ein **CommonMark**-Beispiel.\n";

$document = CommonMark\Parse($markdown);
$html = CommonMark\Render\HTML($document);

echo $html;

<h1>Hallo Welt</h1> <p>Dies ist ein <strong>CommonMark</strong>-Beispiel.</p>

AST traversieren und Links extrahieren

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

$document = CommonMark\Parse($markdown);

// Alle Knoten des Dokuments iterieren
foreach ($document as $node) {
    if ($node instanceof CommonMark\Node\Inline\Link) {
        echo 'Link gefunden: ' . $node->url . PHP_EOL;
    }
}

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

Parsen mit Optionen (unsichere Links erlauben)

<?php
$markdown = "[Klick mich](javascript:alert('XSS'))\n";

// Ohne UNSAFE_LINKS wird der Link gefiltert
$docSafe   = CommonMark\Parse($markdown);
echo CommonMark\Render\HTML($docSafe);

// Mit UNSAFE_LINKS bleibt der Link erhalten
$docUnsafe = CommonMark\Parse($markdown, CommonMark\Parser\UNSAFE_LINKS);
echo CommonMark\Render\HTML($docUnsafe);

<p><a href="">Klick mich</a></p> <p><a href="javascript:alert('XSS')">Klick mich</a></p>

// Wichtig · Fallstricke

Sicherheitshinweis: Verwende niemals die Option CommonMark\Parser\UNSAFE_LINKS bei Nutzereingaben, da dadurch JavaScript-URLs (z. B. javascript:...) und andere potenziell gefährliche Protokolle in Links nicht mehr herausgefiltert werden – dies öffnet XSS-Angriffsvektoren.

Die Funktion gehört zur PECL-Erweiterung ext/commonmark und ist nicht im PHP-Kern enthalten. Sie muss über PECL installiert werden (pecl install commonmark). Stelle sicher, dass eine ausreichend aktuelle Version der zugrundeliegenden C-Bibliothek cmark auf dem System installiert ist.

Der zurückgegebene AST ist mutable – Änderungen am Dokument-Objekt beeinflussen die anschließende Ausgabe direkt. Beim Traversieren größerer Dokumente kann die Performance durch gezielte Knotensuche optimiert werden.

Siehe auch

CommonMark\Render\HTML CommonMark\Render\XML CommonMark\Render\Man CommonMark\Render\CommonMark CommonMark\Node\Document CommonMark\Converter