CommonMark\Node\Image — Klasse · PHP-Referenz

Signatur

class CommonMark\Node\Image extends CommonMark\Node\Inline

Beschreibung

CommonMark\Node\Image ist ein Knoten im abstrakten Syntaxbaum (AST), der von der PHP-CommonMark-Extension erzeugt wird. Er entspricht der Markdown-Syntax ![Alternativtext](URL "Titel") und enthält die Ziel-URL sowie einen optionalen Titel des Bildes.

Über die Eigenschaften url und title lassen sich Bild-URL und Titel lesen und schreiben. Kind-Knoten des Image-Knotens repräsentieren den Alternativtext (in der Regel ein Text-Knoten). Die Klasse erbt von CommonMark\Node\Inline und kann daher überall dort verwendet werden, wo Inline-Knoten erlaubt sind.

Typische Anwendungsfälle sind die programmatische Erstellung von CommonMark-Dokumenten mit Bildern sowie das Traversieren und Manipulieren geparster Dokumente, z. B. um alle Bild-URLs eines Textes zu extrahieren oder zu ersetzen.

url – die Ziel-URL des Bildes (z. B. https://example.com/bild.png)
title – optionaler Tooltip-Titel des Bildes
Kind-Knoten bilden den Alternativtext des Bildes ab.

Parameter

Name	Typ	Default	Beschreibung
$url	string		Die URL des Bildes, die direkt beim Erzeugen eines neuen `Image`-Knotens gesetzt werden kann.
$title	string		Optionaler Titel des Bildes (wird als `title`-Attribut im gerenderten HTML ausgegeben).

Beispiele

Bild-Knoten aus gepartem Dokument extrahieren

<?php
use CommonMark\Parser;
use CommonMark\Node\Image;

$markdown = 'Hier ist ein Bild: ![PHP Logo](https://www.php.net/images/logos/php-logo.png "PHP")';

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

// Alle Bild-Knoten traversieren
foreach ($document->children() as $node) {
    // Inline-Knoten rekursiv durchsuchen
    foreach ($node->children() as $inline) {
        if ($inline instanceof Image) {
            echo 'URL: ' . $inline->url . PHP_EOL;
            echo 'Titel: ' . $inline->title . PHP_EOL;
        }
    }
}

URL: https://www.php.net/images/logos/php-logo.png Titel: PHP

Bild-Knoten programmatisch erstellen und in ein Dokument einfügen

<?php
use CommonMark\Node\Document;
use CommonMark\Node\Paragraph;
use CommonMark\Node\Image;
use CommonMark\Node\Text;
use CommonMark\Render\HTML;

$document = new Document();
$paragraph = new Paragraph();

$image = new Image();
$image->url = 'https://example.com/foto.jpg';
$image->title = 'Ein Beispielbild';

// Alternativtext als Text-Kind-Knoten hinzufügen
$altText = new Text();
$altText->literal = 'Beispiel';
$image->appendChild($altText);

$paragraph->appendChild($image);
$document->appendChild($paragraph);

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

// Wichtig · Fallstricke

Sicherheit: Werden Bild-URLs aus Benutzereingaben übernommen, muss die URL zwingend validiert und bereinigt werden. Ohne Prüfung können schädliche URL-Schemata wie javascript: oder externe Tracking-URLs eingeschleust werden. Nutze Allow-Listen für erlaubte Protokolle (z. B. https).

Die CommonMark\Node\Image-Klasse ist Teil der PECL-Extension commonmark (von Joe Watkins / krakjoe) und steht nicht in der PHP-Standardinstallation zur Verfügung. Sie muss separat installiert werden (pecl install commonmark).

Der Alternativtext wird nicht als einfache String-Eigenschaft gespeichert, sondern als Kind-Knoten-Baum — ähnlich wie bei Link-Knoten. Für einfachen Text reicht ein einzelner Text-Knoten als Kind.

Siehe auch

CommonMark\Node\Link CommonMark\Node\Text CommonMark\Node\Inline CommonMark\Node\Document CommonMark\Parser CommonMark\Render\HTML