# Uvod
Greph je mehanizem za iskanje in preoblikovanje izvornih dreves v čistem PHP. Podpira tri sorodne načine:

- **Iskanje po besedilu** z izhodom, združljivim z grep, in ergonomijo v slogu ripgrep.
- **Iskanje AST** s strukturnimi vzorci PHP in metaspremenljivkami.
- **Prepis AST** s strukturnim preoblikovanjem, ki ohranja oblikovanje.

Vključuje tudi ogrete indeksirane načine za besedilna opravila in opravila AST, pravilnike osveževanja, prilagojene življenjskemu ciklu, ogrete nabore indeksov, podprte z manifestom, ter ovojnice za združljivost `rg` / `sg` za orodja in agentska okolja.

## Zakaj obstaja Greph

Aplikacije in agenti PHP, ki potrebujejo hitro iskanje po kodi, običajno zaženejo izvorna orodja v lupini (`grep`, `ripgrep`, `ast-grep`), s čimer izgubijo prenosljivost in si otežijo uvajanje. Strukturno iskanje in prepisovanje sta še zahtevnejša: običajno je treba povsem zapustiti proces PHP.

Greph odpravi to vrzel. Vaša koda PHP lahko išče po besedilu, išče strukturna ujemanja in prepisuje refaktorirano kodo samo s standardno knjižnico in `nikic/php-parser`. Izhod in izhodne kode so združljivi s kanoničnimi orodji, zato obstoječih skriptov in agentov ni treba spreminjati.

## Kaj omogoča

- Iskanje po nespremenljivih nizih in regularnih izrazih z načini za cele besede, neobčutljivost na velikost črk, kontekst, štetje in samo datoteke
- Strukturno iskanje AST PHP z `$VAR`, `$$$VARIADIC` in ponovljenimi metaspremenljivkami
- Prepis AST, ki ohranja oblikovanje, z načini za suhi zagon, interaktivno uporabo in zapis
- Ogreti besedilni indeksi (tri-grami in pojavnice identifikatorjev) za ponavljajoča se opravila
- Ogreti indeks dejstev AST in predpomnjeno iskanje AST za ponavljajoče se strukturne poizvedbe
- Ogreti indeksi, prilagojeni življenjskemu ciklu: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Iskanje po več indeksih in poimenovanih naborih v ogretih besedilnih indeksih, indeksih dejstev AST in shrambah predpomnilnika AST
- Diagnostika načrtovalnika z `--trace-plan` in označevanjem izvora indeksa pri ogretem iskanju
- Ovojnici za združljivost ripgrep in ast-grep CLI, ki uporabljata isti mehanizem
- Nabor vzporednih delavcev na osnovi pcntl z nadomestnim izvajanjem v enem procesu
- Pregledovalnik datotek, ki upošteva gitignore in `.grephignore` ter zazna binarne datoteke

## Kaj zahteva

- PHP 8.2 ali novejši
- `ext-json`, `ext-ctype` in `ext-tokenizer`, ki so omogočeni v skoraj vsaki gradnji PHP
- `ext-zlib` za predpomnjeno shrambo AST (`greph-index ast-cache`)
- `nikic/php-parser` (edina odvisnost Composer)

Osrednje funkcije za besedilo in AST delujejo v čistem PHP. Izbirne primerjave zmogljivosti so odvisne od zunanjih orodij, kot so `rg`, `grep` in `sg`, vendar jih Greph za delovanje ne potrebuje. Vzporedna pregledovanja uporabljajo `ext-pcntl`, kadar je na voljo, sicer pa nemoteno preklopijo na izvajanje v enem procesu. Gostitelji, ki prepovedujejo `proc_open()` in `shell_exec()`, so obravnavani v razdelku [Gostitelji z omejenimi procesi](https://greph.inline0.dev/sl/docs/advanced/process-restricted-hosts).

## Kratek primer

Izvršne datoteke `vendor/bin` potrebujejo Greph 0.2.3 ali novejši, če je Greph nameščen kot odvisnost vašega projekta.

```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 z [Uvodom](https://greph.inline0.dev/sl/docs/getting-started), nato pa za preostale funkcije uporabite [CLI](https://greph.inline0.dev/sl/docs/cli) in [API](https://greph.inline0.dev/sl/docs/api). Razdelki [Načini](https://greph.inline0.dev/sl/docs/modes/text), [Indeksiranje](https://greph.inline0.dev/sl/docs/indexed/text) in [Združljivost](https://greph.inline0.dev/sl/docs/compatibility/rg) podrobno obravnavajo posamezne poteke dela.