# Wprowadzenie
Greph to napisany w czystym PHP silnik wyszukiwania i refaktoryzacji drzew źródłowych. Obsługuje trzy powiązane tryby:

- **Wyszukiwanie tekstu** z danymi wyjściowymi zgodnymi z grep i ergonomią w stylu ripgrep.
- **Wyszukiwanie AST** ze wzorcami strukturalnymi PHP i metazmiennymi.
- **Przepisywanie AST** z refaktoryzacją strukturalną zachowującą formatowanie.

Udostępnia również rozgrzane tryby indeksowania dla zadań tekstowych i AST, zasady odświeżania uwzględniające cykl życia, zestawy rozgrzanych indeksów oparte na manifeście oraz warstwy zgodności `rg` / `sg` dla narzędzi i środowisk agentów.

## Dlaczego powstało Greph

Aplikacje PHP i agenci, którzy potrzebują szybkiego wyszukiwania kodu, zwykle uruchamiają natywne narzędzia powłoki (`grep`, `ripgrep`, `ast-grep`), tracąc przenośność i utrudniając wdrożenie. Wyszukiwanie strukturalne i przepisywanie są jeszcze trudniejsze: zazwyczaj wymagają całkowitego opuszczenia procesu PHP.

Greph usuwa tę lukę. Kod PHP może wykonywać wyszukiwanie tekstowe, dopasowywać struktury i przepisywać kod w ramach refaktoryzacji, korzystając wyłącznie ze standardowej biblioteki i `nikic/php-parser`. Dane wyjściowe i kody zakończenia są zgodne z kanonicznymi narzędziami, więc istniejące skrypty i agenci nie wymagają zmian.

## Funkcje

- Wyszukiwanie tekstu za pomocą stałych ciągów i wyrażeń regularnych, z dopasowywaniem całych słów, bez rozróżniania wielkości liter, wyświetlaniem kontekstu, zliczaniem wyników i trybem tylko ścieżek plików
- Strukturalne wyszukiwanie AST PHP z użyciem `$VAR`, `$$$VARIADIC` i powtarzanych metazmiennych
- Przepisywanie AST zachowujące formatowanie z trybami symulacji, interaktywnym i zapisu
- Rozgrzane indeksy tekstowe (trygramy + listy identyfikatorów) do powtarzających się zadań
- Rozgrzany indeks faktów AST i buforowane wyszukiwanie AST do powtarzających się zapytań strukturalnych
- Rozgrzane indeksy uwzględniające cykl życia: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Wyszukiwanie obejmujące wiele indeksów i zestawów o nazwach w rozgrzanych magazynach tekstu, faktów AST i buforowanych drzew AST
- Diagnostyka planera z użyciem `--trace-plan` i etykietami pochodzenia indeksu dla wyszukiwania z rozgrzanym indeksem
- Warstwy zgodności ripgrep i ast-grep CLI obsługiwane przez ten sam silnik
- Równoległa pula procesów roboczych oparta na pcntl z możliwością przejścia na jeden proces
- Obsługujący gitignore i `.grephignore` moduł przeglądania plików z wykrywaniem plików binarnych

## Wymagania

- PHP 8.2 lub nowszy
- `ext-json`, `ext-ctype` i `ext-tokenizer`, włączone w niemal każdej kompilacji PHP
- `ext-zlib` dla buforowanego magazynu AST (`greph-index ast-cache`)
- `nikic/php-parser` (jedyna zależność Composer)

Podstawowe funkcje tekstowe i AST działają w czystym PHP. Opcjonalne porównania wydajności wymagają zewnętrznych narzędzi, takich jak `rg`, `grep` i `sg`, ale samo Greph nie potrzebuje ich do działania. Skanowanie równoległe używa `ext-pcntl`, gdy jest dostępne, a w przeciwnym razie płynnie przechodzi na wykonanie w jednym procesie. Informacje o hostach, które blokują `proc_open()` i `shell_exec()`, znajdziesz w sekcji [Hosty z ograniczeniami procesów](https://greph.inline0.dev/pl/docs/advanced/process-restricted-hosts).

## Szybki przykład

Pliki wykonywalne `vendor/bin` wymagają Greph 0.2.3 lub nowszego, gdy Greph jest zainstalowane jako zależność projektu.

```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',
);
```

Zacznij od [Pierwsze kroki](https://greph.inline0.dev/pl/docs/getting-started), a następnie skorzystaj z sekcji [CLI](https://greph.inline0.dev/pl/docs/cli) i [API](https://greph.inline0.dev/pl/docs/api), aby poznać pozostałe funkcje. Sekcje [Tryby](https://greph.inline0.dev/pl/docs/modes/text), [Indeksowanie](https://greph.inline0.dev/pl/docs/indexed/text) i [Zgodność](https://greph.inline0.dev/pl/docs/compatibility/rg) szczegółowo opisują konkretne zastosowania.