Einführung

Greph ist eine vollständig in PHP implementierte Such- und Refactoring-Engine für Quellbäume. Sie bietet drei verwandte Modi:

• Textsuche mit grep-kompatibler Ausgabe und ripgrep-ähnlicher Bedienung.
• AST-Suche mit strukturellen Mustern und Metavariablen für PHP.
• AST-Rewrite für strukturelles Refactoring unter Beibehaltung der Formatierung.

Außerdem bietet das Tool aufgewärmte Indexmodi für Text- und AST-Aufgaben, Aktualisierungsrichtlinien mit Lebenszyklussteuerung, auf Manifesten basierende Gruppen aufgewärmter Indizes sowie Kompatibilitäts-Wrapper für rg und sg in Tool- und Agent-Umgebungen.

Warum es Greph gibt

PHP-Anwendungen und Agents, die schnell im Code suchen müssen, rufen meist native Tools über die Shell auf (grep, ripgrep, ast-grep). Dadurch verlieren sie an Portabilität und der Bereitstellungsaufwand steigt. Bei struktureller Suche und beim Rewrite ist es noch schwieriger: Dafür muss man normalerweise den PHP-Prozess vollständig verlassen.

Greph schließt diese Lücke. Dein PHP-Code kann Textsuchen, strukturelle Treffer und Refactoring-Rewrites ausschließlich mit der Standardbibliothek und nikic/php-parser ausführen. Ausgabe und Exit-Codes sind mit den kanonischen Tools kompatibel, sodass bestehende Skripte und Agents nicht angepasst werden müssen.

Funktionen

• Textsuche mit festen Zeichenfolgen und regulären Ausdrücken, einschließlich Suche nach ganzen Wörtern, ohne Beachtung der Groß- und Kleinschreibung, mit Kontext, Trefferzahlen oder nur Dateinamen
• Strukturelle AST-Suche für PHP mit $VAR, $$$VARIADIC und wiederholten Metavariablen
• AST-Rewrite unter Beibehaltung der Formatierung, mit Probelauf, interaktivem Modus und Schreibmodus
• Aufgewärmte Textindizes (Trigramme und Belegungen für Bezeichner) für wiederholte Aufgaben
• Aufgewärmter AST-Faktenindex und zwischengespeicherte AST-Suche für wiederholte strukturelle Abfragen
• Lebenszyklusgesteuerte, aufgewärmte Indizes: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Suche in mehreren Indizes und benannten Gruppen über aufgewärmte Text-, AST-Fakten- und AST-Cache-Speicher hinweg
• Planner-Diagnosen mit --trace-plan und Kennzeichnung der Indexquelle bei aufgewärmten Suchen
• Kompatibilitäts-Wrapper für ripgrep und ast-grep CLI auf Basis derselben Engine
• Paralleler Worker-Pool auf Basis von pcntl mit Rückfall auf einen einzelnen Prozess
• Dateisuche mit Berücksichtigung von gitignore und .grephignore sowie Erkennung von Binärdateien

Voraussetzungen

• PHP 8.2 oder höher
• ext-json, ext-ctype und ext-tokenizer, die in fast jedem PHP-Build aktiviert sind
• ext-zlib für den zwischengespeicherten AST-Speicher (greph-index ast-cache)
• nikic/php-parser (die einzige Composer-Abhängigkeit)

Text- und AST-Kernfunktionen laufen vollständig in PHP. Optionale Benchmark-Vergleiche setzen externe Tools wie rg, grep und sg voraus, doch Greph selbst benötigt sie nicht. Parallele Scans nutzen, sofern verfügbar, ext-pcntl und wechseln andernfalls problemlos zur Ausführung in einem einzelnen Prozess. Weitere Informationen zu Hosts, die proc_open() und shell_exec() verbieten, findest du unter Hosts mit eingeschränkten Prozessen.

Schnellstart-Beispiel

Die ausführbaren Dateien von vendor/bin benötigen Greph ab Version 0.2.3, wenn Greph als Abhängigkeit deines Projekts installiert ist.

# Text search
vendor/bin/greph -F "function" src

# Structural search
vendor/bin/greph -p 'new $CLASS()' src

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$matches = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true),
);

$asts = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);

Beginne mit Erste Schritte und nutze anschließend CLI sowie API, um den restlichen Funktionsumfang kennenzulernen. Die Abschnitte Modi, Indexiert und Kompatibilität behandeln bestimmte Arbeitsabläufe ausführlich.