CommonMark\Interfaces\IVisitor — Interface · PHP-Referenz

Signatur

interface IVisitor

Beschreibung

Das IVisitor-Interface gehört zur CommonMark-Erweiterung für PHP und bildet das klassische Visitor-Entwurfsmuster ab. Klassen, die dieses Interface implementieren, können einen CommonMark-Dokumentenbaum (AST) knotenweise traversieren und dabei beliebige Verarbeitungslogik ausführen, ohne die Knotenklassen selbst zu verändern.

Das Interface definiert die Methode enter() und/oder leave(), die beim Betreten bzw. Verlassen eines Knotens aufgerufen werden. So lässt sich sowohl eine Top-Down- als auch eine Bottom-Up-Verarbeitung des Baums realisieren. Typische Anwendungsfälle sind das Transformieren von Knoten, das Sammeln von Informationen (z. B. alle Überschriften eines Dokuments) oder das Generieren von Ausgabe-Formaten.

Um einen Besucher auf einen Dokumentenbaum anzuwenden, wird die accept()-Methode eines INode-Objekts mit der Visitor-Instanz aufgerufen. Die Traversierung des gesamten Baums erfolgt dann automatisch rekursiv durch die CommonMark-Erweiterung.

Implementieren Sie IVisitor, wenn Sie den AST analysieren oder umformen möchten, ohne Knotenklassen zu ändern.
Kombinieren Sie mehrere Visitor-Implementierungen für unterschiedliche Verarbeitungsschritte (z. B. Validierung + Transformation).

Beispiele

Einfacher Visitor zum Sammeln aller Überschriften

<?php
use CommonMark\Interfaces\IVisitor;
use CommonMark\Node\Heading;
use CommonMark\Parser;

class HeadingCollector implements IVisitor
{
    public array $headings = [];

    public function enter(\CommonMark\Interfaces\INode $node): ?int
    {
        if ($node instanceof Heading) {
            $this->headings[] = $node->getStringContent();
        }
        return null; // Traversierung normal fortsetzen
    }

    public function leave(\CommonMark\Interfaces\INode $node): void
    {
        // nichts zu tun beim Verlassen
    }
}

$parser = new Parser();
$document = $parser->parse("# Kapitel 1\n\nText\n\n## Abschnitt 1.1\n");

$collector = new HeadingCollector();
$document->accept($collector);

print_r($collector->headings);

Array ( [0] => Kapitel 1 [1] => Abschnitt 1.1 )

Visitor zur Transformation von Knoten (Textknoten verarbeiten)

<?php
use CommonMark\Interfaces\IVisitor;
use CommonMark\Node\Text;
use CommonMark\Parser;
use CommonMark\Renderer\Html;

class UpperCaseTextVisitor implements IVisitor
{
    public function enter(\CommonMark\Interfaces\INode $node): ?int
    {
        if ($node instanceof Text) {
            $node->setLiteral(strtoupper($node->getLiteral()));
        }
        return null;
    }

    public function leave(\CommonMark\Interfaces\INode $node): void {}
}

$parser   = new Parser();
$document = $parser->parse("Hallo Welt\n");

$document->accept(new UpperCaseTextVisitor());

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

<p>HALLO WELT</p>

// Wichtig · Fallstricke

Das IVisitor-Interface stammt aus der PECL-Erweiterung CommonMark (ext-cmark) und ist nicht Teil der Standard-PHP-Distribution. Es muss separat installiert werden. Die genauen Methodensignaturen (enter(), leave()) können je nach Version der Erweiterung leicht abweichen — prüfen Sie stets die aktuelle Dokumentation der installierten Version.

Der Rückgabewert von enter() kann genutzt werden, um die Traversierung zu steuern: Gibt die Methode eine entsprechende Konstante zurück, lässt sich das Absteigen in Kindknoten unterdrücken oder die gesamte Traversierung abbrechen.

Siehe auch

CommonMark\Interfaces\INode CommonMark\Parser CommonMark\Node