# Úvod
Greph je čistě PHP engine pro vyhledávání a refaktorování zdrojových stromů. Nabízí tři související režimy:

- **Textové vyhledávání** s výstupem kompatibilním s grep a ergonomií ve stylu ripgrep.
- **Vyhledávání AST** se strukturálními vzory PHP a metavariablami.
- **Přepis AST** se strukturálním refaktorováním, které zachovává formátování.

Nabízí také připravené indexované režimy pro textové i AST úlohy, zásady obnovy zohledňující životní cyklus, sady připravených indexů podložené manifestem a obaly kompatibility `rg` / `sg` pro prostředí nástrojů a agentů.

## Proč Greph vznikl

Aplikace PHP a agenti, kteří potřebují rychlé vyhledávání v kódu, obvykle spouštějí nativní nástroje z příkazového řádku (`grep`, `ripgrep`, `ast-grep`), čímž se vzdávají přenositelnosti a komplikují nasazení. Strukturální vyhledávání a přepis jsou na tom ještě hůř: obvykle vyžadují opustit proces PHP úplně.

Greph tuto mezeru odstraňuje. Váš kód PHP může provádět textové vyhledávání, strukturální porovnávání i refaktoringové přepisy pouze pomocí standardní knihovny a `nikic/php-parser`. Výstup i návratové kódy jsou kompatibilní s kanonickými nástroji, takže stávající skripty a agenti nevyžadují úpravy.

## Co umí

- Vyhledávání textu pomocí pevných řetězců a regulárních výrazů, včetně režimů celých slov, bez rozlišování velikosti písmen, s kontextem, počty a pouze se soubory
- Strukturální vyhledávání AST PHP pomocí `$VAR`, `$$$VARIADIC` a opakovaných metavariabel
- Přepis AST se zachováním formátování, v režimu náhledu, interaktivním režimu i režimu zápisu
- Připravené textové indexy (trigramy a seznamy výskytů identifikátorů) pro opakované úlohy
- Připravený index faktů AST a vyhledávání AST v mezipaměti pro opakované strukturální dotazy
- Připravené indexy s životním cyklem: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Vyhledávání ve více indexech a pojmenovaných sadách napříč připravenými úložišti textu, faktů AST a mezipamětí AST
- Diagnostika plánovače pomocí `--trace-plan` a označování původu indexu při připraveném vyhledávání
- Obaly kompatibility ripgrep a ast-grep CLI využívající stejný engine
- Paralelní fond pracovních procesů založený na pcntl s náhradním jednovláknovým režimem
- Procházení souborů respektující gitignore a `.grephignore` s detekcí binárních souborů

## Co vyžaduje

- PHP 8.2 nebo novější
- `ext-json`, `ext-ctype` a `ext-tokenizer`, které jsou povoleny téměř v každé sestavě PHP
- `ext-zlib` pro úložiště AST v mezipaměti (`greph-index ast-cache`)
- `nikic/php-parser` (jediná závislost Composer)

Základní textové funkce a funkce AST běží v čistém PHP. Volitelné srovnání výkonu závisí na externích nástrojích, jako jsou `rg`, `grep` a `sg`, samotné Greph je však ke svému fungování nepotřebuje. Paralelní skenování využívá `ext-pcntl`, je-li k dispozici, jinak bez problémů přejde na jeden proces. Hostitelům, kteří zakazují `proc_open()` a `shell_exec()`, se věnuje stránka [Hostitelé s omezenými procesy](https://greph.inline0.dev/cs/docs/advanced/process-restricted-hosts).

## Rychlý příklad

Spustitelné soubory `vendor/bin` vyžadují Greph 0.2.3 nebo novější, pokud je Greph nainstalován jako závislost vašeho 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čněte částí [Začínáme](https://greph.inline0.dev/cs/docs/getting-started) a pak si projděte [CLI](https://greph.inline0.dev/cs/docs/cli) a [API](https://greph.inline0.dev/cs/docs/api), kde najdete zbytek funkcí. Konkrétní postupy podrobně popisují části [Režimy](https://greph.inline0.dev/cs/docs/modes/text), [Indexované](https://greph.inline0.dev/cs/docs/indexed/text) a [Kompatibilita](https://greph.inline0.dev/cs/docs/compatibility/rg).