Signatur
Beschreibung
CommonMark\CQL (CommonMark Query Language) ist eine Klasse der PHP-Erweiterung commonmark, die das gezielte Traversieren eines geparsten CommonMark-Dokumentbaums ermöglicht. Über kompakte Pfadausdrücke können Knoten relativ zu einem Startknoten ausgewählt werden, ohne manuell durch den Baum zu iterieren.
Die unterstützten Navigationspfade orientieren sich an der Baumstruktur eines CommonMark-Dokuments: firstChild und lastChild adressieren das erste bzw. letzte Kindelement eines Knotens, previous und next navigieren zu Geschwisterknoten, und parent steigt eine Ebene im Baum auf. Diese Pfade können zu längeren Ausdrücken verkettet werden, um tiefere Strukturen zu erreichen.
CommonMark\CQL-Objekte werden mit einem Pfad-String konstruiert und sind anschließend als aufrufbare Objekte (Invokables) nutzbar: Der Aufruf mit einem Startknoten und einer Callback-Funktion führt den Pfad aus und ruft den Callback für jeden gefundenen Knoten auf. Dies erleichtert z. B. das selektive Auslesen, Manipulieren oder Prüfen bestimmter Dokumentteile.
Die Klasse ist nützlich, wenn man gezielt auf bestimmte Teile eines geparsten Markdown-Dokuments zugreifen möchte, ohne den gesamten Baum manuell rekursiv zu durchsuchen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $expression Pflicht | string | Ein CQL-Pfadausdruck, der die Navigationsschritte im Baum beschreibt, z. B. 'firstChild/next' oder 'parent/lastChild'. Die Schritte werden durch / getrennt. |
Rückgabewert
Beispiele
Navigation zum ersten Kind eines Knotens
<?php
use CommonMark\Parser;
use CommonMark\CQL;
$parser = new Parser();
$document = $parser->parse("# Überschrift\n\nErster Absatz.\n\nZweiter Absatz.");
// CQL-Ausdruck: navigiere zum ersten Kind des Dokuments
$cql = new CQL('firstChild');
$cql($document, function ($node) {
echo get_class($node) . "\n";
});Verkettete Navigation: nächstes Geschwisterelement des ersten Kindes
<?php
use CommonMark\Parser;
use CommonMark\CQL;
$parser = new Parser();
$document = $parser->parse("# Überschrift\n\nErster Absatz.\n\nZweiter Absatz.");
// CQL-Ausdruck: erstes Kind, dann das nächste Geschwisterelement
$cql = new CQL('firstChild/next');
$cql($document, function ($node) {
echo get_class($node) . "\n";
});Elternknoten eines Kindknotens ermitteln
<?php
use CommonMark\Parser;
use CommonMark\CQL;
$parser = new Parser();
$document = $parser->parse("# Überschrift\n\nEin Absatz.");
// CQL: erstes Kind, dann dessen erstes Kind, dann zurück zum Elternknoten
$cql = new CQL('firstChild/firstChild/parent');
$cql($document, function ($node) {
echo get_class($node) . "\n";
});// Wichtig · Fallstricke
Hinweis zur Erweiterung: CommonMark\CQL ist Teil der PECL-Erweiterung commonmark und steht nicht in einer Standard-PHP-Installation zur Verfügung. Die Erweiterung muss separat installiert werden.
Ungültige Pfadausdrücke führen zu einer CommonMark\Exception\RuntimeException. Erlaubte Segmente sind ausschließlich: firstChild, lastChild, previous, next und parent. Tippfehler oder andere Schlüsselwörter werden nicht akzeptiert.
Navigiert ein Pfad auf einen nicht existierenden Knoten (z. B. next beim letzten Geschwisterknoten), wird der Callback für diesen Pfadschritt nicht aufgerufen — es tritt kein Fehler auf.