Signatur
Beschreibung
CommonMark\Render ist Teil der PHP-Erweiterung CommonMark (PECL) und wandelt einen zuvor geparsten CommonMark\Node\Document-Knoten in HTML-Ausgabe um. Sie wird üblicherweise zusammen mit CommonMark\Parse verwendet: Zuerst wird Markdown-Text eingelesen und zu einem AST (Abstract Syntax Tree) geparst, danach wird dieser AST mit CommonMark\Render in HTML gerendert.
Die Funktion unterstützt optionale Renderoptionen, die über Integer-Flags gesteuert werden. Zu den verfügbaren Flags gehören z. B. CommonMark\Render\Sourcepos (fügt Quellpositionsangaben in die HTML-Ausgabe ein), CommonMark\Render\HardBreaks (erzwingt harte Zeilenumbrüche) und weitere, die das Ausgabeverhalten beeinflussen.
Ein typischer Einsatz dieser Funktion ist die sichere Darstellung von Benutzer-Markdown-Inhalten in Webanwendungen, wobei zunächst geparstes Markdown in HTML überführt wird. Der AST erlaubt außerdem Transformationen vor dem eigentlichen Rendering, was eine flexible Verarbeitung ermöglicht.
Hinweis: Die CommonMark-Erweiterung ist nicht im PHP-Core enthalten und muss separat über PECL installiert werden (pecl install commonmark).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $node Pflicht | CommonMark\Node\Document | Das geparste CommonMark-Dokumentknoten-Objekt, das gerendert werden soll. In der Regel das Rückgabeergebnis von CommonMark\Parse(). |
|
| $options | int | 0 | Optionale Bitmaske aus Render-Flags. Mögliche Werte sind z. B. CommonMark\Render\Sourcepos, CommonMark\Render\HardBreaks, CommonMark\Render\Safe oder CommonMark\Render\NoBreaks. Standardmäßig sind keine zusätzlichen Optionen aktiv. |
Rückgabewert
\Error-Exception ausgelöst.Beispiele
Einfaches Markdown zu HTML rendern
<?php
// Markdown-Text parsen
$markdown = "# Hallo Welt\n\nDies ist **fetter** Text mit einem [Link](https://example.com).";
$document = CommonMark\Parse($markdown);
// Gerenderten HTML-String erzeugen
$html = CommonMark\Render($document);
echo $html;Rendering mit Quellpositions-Angaben (Sourcepos)
<?php
$markdown = "## Abschnitt\n\nEin kurzer Absatz.";
$document = CommonMark\Parse($markdown);
// Sourcepos-Flag aktivieren: fügt data-sourcepos-Attribute ein
$html = CommonMark\Render($document, CommonMark\Render\Sourcepos);
echo $html;Sicheres Rendering mit Safe-Flag (verhindert Raw-HTML)
<?php
// Benutzereingabe, die potenziell gefährliches HTML enthält
$userInput = "Normaler Text\n\n<script>alert('XSS');</script>\n\n**Fett**";
$document = CommonMark\Parse($userInput);
// Mit Safe-Flag wird eingebettetes Raw-HTML unterdrückt
$html = CommonMark\Render($document, CommonMark\Render\Safe);
echo $html;// Wichtig · Fallstricke
Sicherheit: Ohne das Flag CommonMark\Render\Safe wird in Markdown eingebettetes Raw-HTML unverändert in die Ausgabe übernommen. Dies kann zu XSS-Angriffen führen, wenn die Eingabe von Benutzern stammt. Verwende daher immer das Safe-Flag bei nicht vertrauenswürdigen Eingaben oder bereinige die HTML-Ausgabe zusätzlich mit einer Bibliothek wie HTMLPurifier.
Die CommonMark-Erweiterung ist eine PECL-Erweiterung und nicht standardmäßig in PHP vorhanden. Stelle sicher, dass ext-commonmark in deiner composer.json als Abhängigkeit deklariert ist oder dass die Erweiterung serverseitig installiert und aktiviert ist.
Der AST (CommonMark\Node\Document) kann vor dem Rendering programmatisch verändert werden (Knoten hinzufügen, entfernen, traversieren), was CommonMark\Render besonders flexibel einsetzbar macht.