# 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](https://greph.inline0.dev/de/docs/advanced/process-restricted-hosts).

## 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.

```bash
# 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
```

```php
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](https://greph.inline0.dev/de/docs/getting-started) und nutze anschließend [CLI](https://greph.inline0.dev/de/docs/cli) sowie [API](https://greph.inline0.dev/de/docs/api), um den restlichen Funktionsumfang kennenzulernen. Die Abschnitte [Modi](https://greph.inline0.dev/de/docs/modes/text), [Indexiert](https://greph.inline0.dev/de/docs/indexed/text) und [Kompatibilität](https://greph.inline0.dev/de/docs/compatibility/rg) behandeln bestimmte Arbeitsabläufe ausführlich.