CommonMark\Node\Link — Klasse · PHP-Referenz

Signatur

class CommonMark\Node\Link extends CommonMark\Node

Beschreibung

CommonMark\Node\Link ist Teil der PHP-Erweiterung commonmark (ext-commonmark) und bildet einen Hyperlink im Abstract Syntax Tree eines CommonMark-Dokuments ab. Ein Link in Markdown wie [Linktext](https://example.com "Titel") wird beim Parsen als Link-Knoten erzeugt, der die URL in der Eigenschaft url und den optionalen Titel in title speichert. Der sichtbare Linktext wird als Kindknoten (z. B. Text-Knoten) untergeordnet.

Die Klasse erbt von CommonMark\Node und stellt damit alle allgemeinen Baumoperationen wie das Traversieren, Einfügen oder Entfernen von Knoten zur Verfügung. Über die öffentlichen Eigenschaften url und title lassen sich Ziel-URL und Linktitel sowohl lesen als auch schreiben, was eine vollständige Manipulation des AST erlaubt – etwa um Links umzuschreiben oder zu filtern, bevor das Dokument in HTML gerendert wird.

Link-Knoten werden typischerweise nicht manuell instanziiert, sondern entstehen beim Aufruf von CommonMark\Parser::parse(). Mithilfe eines CommonMark\CQL-Ausdrucks oder durch rekursives Traversieren des Baums können alle Links in einem Dokument gezielt gefunden und verändert werden.

url – die Ziel-URL des Links (lesen/schreiben)
title – der optionale Tooltip-Titel (lesen/schreiben, kann null sein)

Parameter

Name	Typ	Default	Beschreibung
$url	string		Die Ziel-URL des Links, z. B. `https://example.com`. Kann beim Erstellen eines neuen Knotens angegeben werden.
$title	string\|null	null	Optionaler Titel des Links (wird in HTML als `title`-Attribut gerendert). Ist `null`, wenn kein Titel im Markdown angegeben wurde.

Beispiele

Links aus einem geparsten Dokument auslesen

<?php
use CommonMark\Parser;
use CommonMark\Node\Link;
use CommonMark\Node\Document;

$markdown = 'Besuche [PHP.net](https://www.php.net "Die PHP-Website") oder [Google](https://www.google.com).';

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

// Alle Knoten traversieren und Links sammeln
$walker = $document->walker();
while ($event = $walker->next()) {
    $node = $event->getNode();
    if ($node instanceof Link && $event->isEntering()) {
        echo 'URL:   ' . $node->url . PHP_EOL;
        echo 'Titel: ' . ($node->title ?? '(kein Titel)') . PHP_EOL;
        echo '---' . PHP_EOL;
    }
}

URL: https://www.php.net Titel: Die PHP-Website --- URL: https://www.google.com Titel: (kein Titel) ---

URLs in Links programmatisch umschreiben

<?php
use CommonMark\Parser;
use CommonMark\Renderer\HTML;
use CommonMark\Node\Link;

$markdown = 'Mehr Infos unter [Beispiel](http://example.com) und [Test](http://test.example.com).';

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

// Alle http-Links auf https umschreiben
$walker = $document->walker();
while ($event = $walker->next()) {
    $node = $event->getNode();
    if ($node instanceof Link && $event->isEntering()) {
        if (str_starts_with($node->url, 'http://')) {
            $node->url = 'https://' . substr($node->url, 7);
        }
    }
}

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

<p>Mehr Infos unter <a href="https://example.com">Beispiel</a> und <a href="https://test.example.com">Test</a>.</p>

Neuen Link-Knoten manuell erstellen und in den Baum einfügen

<?php
use CommonMark\Node\Link;
use CommonMark\Node\Text;
use CommonMark\Node\Paragraph;
use CommonMark\Node\Document;
use CommonMark\Renderer\HTML;

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

$link = new Link();
$link->url   = 'https://programmierung.net';
$link->title = 'Programmierung.net';

$text = new Text();
$text->literal = 'Zur Startseite';

$link->appendChild($text);
$paragraph->appendChild($link);
$document->appendChild($paragraph);

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

<p><a href="https://programmierung.net" title="Programmierung.net">Zur Startseite</a></p>

// Wichtig · Fallstricke

Sicherheitshinweis: Beim Rendern von Links aus nicht vertrauenswürdigem Markdown kann die url-Eigenschaft beliebige Werte wie javascript:alert(1) enthalten. Filtere oder validiere die URL stets, bevor das HTML ausgegeben wird, um XSS-Angriffe zu verhindern. Die CommonMark-Spezifikation erlaubt prinzipiell alle URL-Schemata.

Die Klasse gehört zur PHP-Erweiterung ext-commonmark (PECL), die separat installiert werden muss (pecl install commonmark). Sie ist nicht in der PHP-Standardinstallation enthalten. Alternativ gibt es die reine PHP-Bibliothek league/commonmark, die eine ähnliche, jedoch nicht kompatible API bietet.

Das direkte Schreiben auf url und title verändert den AST in-place – ein erneutes Parsen ist nicht nötig. Achte darauf, dass du nur im isEntering()-Zweig des Walkers Änderungen vornimmst, um Doppelverarbeitung zu vermeiden.

Siehe auch

CommonMark\Node CommonMark\Node\Image CommonMark\Node\Text CommonMark\Parser CommonMark\Renderer\HTML CommonMark\CQL