# Úvod
Greph je čistý nástroj na vyhľadávanie a refaktorovanie zdrojových stromov v PHP. Ponúka tri súvisiace režimy:

- **Textové vyhľadávanie** s výstupom kompatibilným s grep a používateľským prostredím v štýle ripgrep.
- **Vyhľadávanie v AST** so štrukturálnymi vzormi PHP a metavariabilnými premennými.
- **Prepisovanie AST** so štrukturálnym refaktorovaním, ktoré zachováva formátovanie.

Obsahuje aj zahriate indexované režimy pre textové aj AST úlohy, pravidlá obnovovania zohľadňujúce životný cyklus, súpravy zahriatych indexov založené na manifeste a obaly kompatibilné s `rg` a `sg` pre nástroje a agentov.

## Prečo existuje Greph

Aplikácie PHP a agenti, ktorí potrebujú rýchlo vyhľadávať v kóde, zvyčajne spúšťajú natívne nástroje cez shell (`grep`, `ripgrep`, `ast-grep`), čím sa vzdávajú prenositeľnosti a komplikujú nasadenie. So štrukturálnym vyhľadávaním a prepisovaním je to ešte horšie: zvyčajne si vyžaduje úplne opustiť proces PHP.

Greph túto medzeru vypĺňa. Váš kód PHP môže vykonávať textové vyhľadávania, štrukturálne porovnávanie a refaktoračné prepisovanie iba pomocou štandardnej knižnice a `nikic/php-parser`. Výstup a návratové kódy sú kompatibilné s kanonickými nástrojmi, takže existujúce skripty a agentov netreba meniť.

## Čo dokáže

- Textové vyhľadávanie presných reťazcov a regulárnych výrazov s režimami pre celé slová, nerozlišovanie veľkosti písmen, kontext, počet zhôd a vyhľadávanie iba v názvoch súborov
- Štrukturálne vyhľadávanie v AST PHP pomocou `$VAR`, `$$$VARIADIC` a opakovaných metavariabilných premenných
- Prepisovanie AST so zachovaním formátovania v režimoch skúšobného spustenia, interaktívneho režimu a zápisu
- Zahriate textové indexy (trigramy a zoznamy výskytov identifikátorov) pre opakované úlohy
- Zahriaty index faktov AST a vyhľadávanie v AST s vyrovnávacou pamäťou pre opakované štrukturálne dopyty
- Zahriate indexy so zohľadnením životného cyklu: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Vyhľadávanie vo viacerých indexoch a pomenovaných súpravách v zahriatych úložiskách textu, faktov AST a vyrovnávacej pamäte AST
- Diagnostika plánovača pomocou `--trace-plan` a označovanie pôvodu indexu pri vyhľadávaní so zahriatymi indexmi
- Obaly kompatibilné s ripgrep a ast-grep CLI, ktoré využívajú rovnaký nástroj
- Paralelná skupina pracovníkov založená na pcntl s náhradným režimom jedného procesu
- Prehliadač súborov, ktorý zohľadňuje gitignore a `.grephignore` a rozpoznáva binárne súbory

## Čo vyžaduje

- PHP 8.2 alebo novší
- `ext-json`, `ext-ctype` a `ext-tokenizer`, ktoré sú povolené takmer v každom zostavení PHP
- `ext-zlib` pre úložisko AST s vyrovnávacou pamäťou (`greph-index ast-cache`)
- `nikic/php-parser` (jediná závislosť Composer)

Základné funkcie pre text a AST fungujú v čistom PHP. Voliteľné porovnávanie benchmarkov závisí od externých nástrojov, ako sú `rg`, `grep` a `sg`, no samotný Greph na ich fungovanie nepotrebuje. Pri paralelnom skenovaní sa v prípade dostupnosti používa `ext-pcntl`, inak sa bez problémov prejde na vykonávanie v jednom procese. Hostiteľom, ktoré zakazujú `proc_open()` a `shell_exec()`, sa venuje časť [Hostitelia s obmedzenými procesmi](https://greph.inline0.dev/sk/docs/advanced/process-restricted-hosts).

## Rýchly príklad

Na spustenie spustiteľných súborov `vendor/bin` potrebujete Greph 0.2.3 alebo novší, ak je Greph nainštalovaný ako závislosť vášho 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',
);
```

Začnite časťou [Začíname](https://greph.inline0.dev/sk/docs/getting-started) a potom si v častiach [CLI](https://greph.inline0.dev/sk/docs/cli) a [API](https://greph.inline0.dev/sk/docs/api) pozrite zvyšok funkcií. Časti [Režimy](https://greph.inline0.dev/sk/docs/modes/text), [Indexovanie](https://greph.inline0.dev/sk/docs/indexed/text) a [Kompatibilita](https://greph.inline0.dev/sk/docs/compatibility/rg) podrobne opisujú konkrétne pracovné postupy.