Signatur
Beschreibung
CommonMark\Node\HTMLBlock ist ein Knotentyp der CommonMark-Erweiterung für PHP und bildet einen rohen HTML-Block ab, der direkt im Markdown-Quelltext eingebettet ist. Solche Blöcke beginnen und enden gemäß der CommonMark-Spezifikation mit bestimmten HTML-Tags oder Konstrukten (z. B. <div>, Kommentare, Processing-Instructions) auf eigenen Zeilen.
Beim Parsen von Markdown-Dokumenten mit CommonMark\Parser entsteht für jeden erkannten HTML-Block ein entsprechendes HTMLBlock-Objekt im Syntaxbaum. Über dieses Objekt lässt sich der rohe HTML-Inhalt des Blocks auslesen und bei Bedarf manipulieren, bevor das Dokument gerendert wird.
Der Knoten ist besonders nützlich, wenn man den AST traversiert und zwischen reinen Markdown-Knoten und eingebetteten HTML-Passagen unterscheiden möchte – etwa um HTML-Blöcke zu filtern, zu ersetzen oder zu analysieren. Über die Eigenschaft literal lässt sich der rohe HTML-Inhalt lesen und schreiben.
Hinweis: HTMLBlock unterscheidet sich von CommonMark\Node\HTMLInline, das für inline-HTML (z. B. <em> mitten im Text) zuständig ist. HTML-Blöcke umfassen immer ganze Absätze oder eigenständige Block-Elemente.
Beispiele
HTML-Blöcke im CommonMark-AST erkennen und ausgeben
<?php
use CommonMark\Parser;
use CommonMark\Node\HTMLBlock;
use CommonMark\Interfaces\IVisitor;
use CommonMark\Interfaces\IVisitable;
$markdown = <<<MD
# Überschrift
<div class="hinweis">
<p>Dies ist ein roher HTML-Block.</p>
</div>
Ein normaler Absatz.
MD;
$parser = new Parser();
$document = $parser->parse($markdown);
// AST traversieren und HTML-Blöcke finden
function traverseNodes($node): void {
if ($node instanceof HTMLBlock) {
echo "HTML-Block gefunden:\n";
echo $node->literal . "\n";
}
// Kinder besuchen
$child = $node->firstChild;
while ($child !== null) {
traverseNodes($child);
$child = $child->next;
}
}
traverseNodes($document);HTML-Blöcke im AST durch Platzhalter ersetzen
<?php
use CommonMark\Parser;
use CommonMark\Node\HTMLBlock;
use CommonMark\Render\HTML as HTMLRenderer;
$markdown = <<<MD
Text davor.
<script>alert('xss');</script>
Text danach.
MD;
$parser = new Parser();
$document = $parser->parse($markdown);
// Alle HTMLBlock-Knoten bereinigen
function sanitizeHTMLBlocks($node): void {
if ($node instanceof HTMLBlock) {
// Rohen HTML-Inhalt durch Kommentar ersetzen
$node->literal = "<!-- HTML-Block entfernt -->\n";
}
$child = $node->firstChild;
while ($child !== null) {
$next = $child->next;
sanitizeHTMLBlocks($child);
$child = $next;
}
}
sanitizeHTMLBlocks($document);
$renderer = new HTMLRenderer();
echo $renderer->render($document);// Wichtig · Fallstricke
Sicherheitshinweis: Rohe HTML-Blöcke können beliebigen HTML-Code enthalten, inklusive <script>-Tags oder Event-Handler-Attributen. Wenn Benutzereingaben als Markdown verarbeitet werden, sollten HTML-Blöcke entweder vollständig deaktiviert (Option html_block im Parser abschalten) oder vor der Ausgabe sorgfältig bereinigt werden, um XSS-Angriffe zu verhindern.
Die Klasse gehört zur PHP-Extension commonmark (PECL), die auf der CommonMark-Spezifikation basiert. Stellen Sie sicher, dass die Extension korrekt installiert ist (pecl install commonmark), bevor Sie diese Klasse verwenden.
Das Attribut literal enthält den rohen, ungeparsten HTML-Inhalt inklusive öffnender und schließender Tags sowie Zeilenumbrüche, genau wie er im ursprünglichen Markdown-Dokument stand.