Signatur
Beschreibung
CommonMark\Node\CustomBlock ist eine Knotenklasse der PHP-Erweiterung commonmark (basierend auf libcmark) und repräsentiert einen benutzerdefinierten Block-Knoten innerhalb des abstrakten Syntaxbaums (AST) eines CommonMark-Dokuments. Block-Knoten nehmen eine eigene Zeile (bzw. mehrere Zeilen) im Dokument ein – im Gegensatz zu Inline-Knoten, die innerhalb einer Zeile eingebettet sind.
Ein CustomBlock-Knoten erlaubt es, beim Rendern oder Verarbeiten des AST eigene Darstellungslogik einzubinden. Dabei können sowohl ein On-Enter- als auch ein On-Exit-Literal gesetzt werden, die beim Rendern des Knotens ausgegeben werden. Dies eignet sich z. B. für Wrapper-Elemente, benutzerdefinierte Container oder Template-Platzhalter.
Die Klasse erbt die allgemeine Baum-Navigation von CommonMark\Node (z. B. parent, firstChild, lastChild, next, previous) und fügt die spezifischen Eigenschaften onEnter und onExit hinzu, die den Text enthalten, der beim Betreten bzw. Verlassen des Blocks eingesetzt wird.
Typische Anwendungsfälle sind die programmatische Erweiterung eines geparsten CommonMark-Dokuments um eigene Blöcke oder die Manipulation des AST vor dem abschließenden Rendering-Schritt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $onEnter | string | Optionaler Text, der beim Betreten des benutzerdefinierten Blocks im gerenderten Dokument ausgegeben wird. Entspricht der Eigenschaft onEnter des Objekts. |
|
| $onExit | string | Optionaler Text, der beim Verlassen des benutzerdefinierten Blocks im gerenderten Dokument ausgegeben wird. Entspricht der Eigenschaft onExit des Objekts. |
Rückgabewert
Beispiele
Benutzerdefinierten Block-Knoten erstellen und in den AST einfügen
<?php
use CommonMark\Node\CustomBlock;
use CommonMark\Node\Document;
use CommonMark\Node\Paragraph;
use CommonMark\Render;
// Neues Dokument und einen Absatz anlegen
$document = new Document();
$paragraph = new Paragraph();
// CustomBlock mit On-Enter- und On-Exit-Literalen
$customBlock = new CustomBlock();
$customBlock->onEnter = '<div class="custom-block">';
$customBlock->onExit = '</div>';
// Absatz als Kind des CustomBlock, diesen dann an das Dokument hängen
$customBlock->appendChild($paragraph);
$document->appendChild($customBlock);
// Dokument rendern
echo Render\Html($document);Geparsten AST um einen CustomBlock erweitern
<?php
use CommonMark\Parse;
use CommonMark\Node\CustomBlock;
use CommonMark\Render;
$markdown = "Hallo Welt";
$document = Parse($markdown);
// CustomBlock als Wrapper um den gesamten Dokumentinhalt
$wrapper = new CustomBlock();
$wrapper->onEnter = '<section class="markdown-body">';
$wrapper->onExit = '</section>';
// Alle vorhandenen Kinder in den Wrapper verschieben
$child = $document->firstChild;
while ($child !== null) {
$next = $child->next;
$wrapper->appendChild($child);
$child = $next;
}
$document->appendChild($wrapper);
echo Render\Html($document);// Wichtig · Fallstricke
Erweiterungsabhängigkeit: Die Klasse ist nur verfügbar, wenn die PECL-Erweiterung commonmark installiert und aktiviert ist (pecl install commonmark). Sie ist kein Bestandteil des PHP-Kerns.
Sicherheitshinweis: Die Werte von onEnter und onExit werden beim Rendern unverändert in die Ausgabe übernommen. Werden diese Werte aus Benutzereingaben befüllt, besteht XSS-Gefahr. Solche Eingaben müssen vor der Zuweisung mit htmlspecialchars() oder einer geeigneten Sanitization-Bibliothek bereinigt werden.
Die genaue Konstruktor-Signatur (Argumente direkt im Konstruktor) kann je nach Erweiterungsversion variieren; in manchen Versionen werden onEnter und onExit ausschließlich als Objekteigenschaften nach der Instantiierung gesetzt.