# Johdanto
Greph on puhtaalla PHP-kielellä toteutettu lähdekoodipuiden haku- ja refaktorointimoottori. Se kattaa kolme toisiinsa liittyvää tilaa:

- **Tekstihaku** grep-yhteensopivalla tulosteella ja ripgrep-tyylisellä käyttömukavuudella.
- **AST-haku** PHP-rakenteellisilla kuvioilla ja metamuuttujilla.
- **AST-uudelleenkirjoitus** rakenteelliseen refaktorointiin muotoilun säilyttäen.

Mukana ovat myös lämpimät indeksoidut tilat sekä teksti- että AST-työkuormille, elinkaaren huomioivat päivityskäytännöt, manifestiin perustuvat lämpimät indeksijoukot sekä `rg`- ja `sg`-yhteensopivuuskääreet työkalu- ja agenttiympäristöihin.

## Miksi Greph on olemassa

PHP-sovellukset ja agentit, jotka tarvitsevat nopeaa koodihakua, turvautuvat yleensä järjestelmän omiin työkaluihin (`grep`, `ripgrep`, `ast-grep`), jolloin siirrettävyys kärsii ja käyttöönotto vaikeutuu. Rakenteellinen haku ja uudelleenkirjoitus ovat vielä hankalampia: ne edellyttävät tavallisesti poistumista kokonaan PHP-prosessista.

Greph poistaa tämän aukon. PHP-koodillasi voit tehdä tekstihakuja, rakenteellisia hakuja ja refaktorointiin liittyviä uudelleenkirjoituksia pelkän standardikirjaston ja `nikic/php-parser`-työkalun avulla. Tulosteet ja poistumiskoodit ovat yhteensopivia kanonisten työkalujen kanssa, joten olemassa olevia skriptejä ja agentteja ei tarvitse muuttaa.

## Mitä se tekee

- Kiinteän merkkijonon ja säännöllisten lausekkeiden tekstihaku; mukana kokonaisten sanojen haku, kirjainkoon sivuuttaminen, konteksti, osumamäärät ja vain tiedostojen haku
- Rakenteellinen PHP-AST-haku: `$VAR`, `$$$VARIADIC` ja toistuvat metamuuttujat
- AST:n muotoilun säilyttävä uudelleenkirjoitus koeajolla, vuorovaikutteisella tilalla ja kirjoitustilalla
- Lämpimät tekstihakemistot (trigrammit ja tunnisteiden esiintymälistat) toistuviin työkuormiin
- Lämmin AST-faktaindeksi ja välimuistiin tallennettu AST-haku toistuviin rakenteellisiin kyselyihin
- Elinkaaren huomioivat lämpimät indeksit: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Haku useista indekseistä ja nimetyistä joukoista lämpimissä teksti-, AST-fakta- ja AST-välimuistitallennuksissa
- Suunnittelijan diagnostiikka: `--trace-plan` ja indekseistä kertovat tunnisteet lämpimissä hauissa
- ripgrep- ja ast-grep-yhteensopivuuskääreet CLI-toiminnolle; taustalla on sama moottori
- pcntl-pohjainen rinnakkaisten työntekijöiden joukko ja yhden prosessin vararatkaisu
- gitignore- ja `.grephignore`-määrityksiä noudattava tiedostokävelijä, joka tunnistaa binääritiedostot

## Vaatimukset

- PHP 8.2 tai uudempi
- `ext-json`, `ext-ctype` ja `ext-tokenizer`, jotka ovat käytössä lähes jokaisessa PHP-koontiversiossa
- `ext-zlib` välimuistissa säilytettävään AST-tallennukseen (`greph-index ast-cache`)
- `nikic/php-parser` (ainoa Composer-riippuvuus)

Tekstin ja AST:n ydintoiminnot toimivat puhtaalla PHP-kielellä. Valinnaiset vertailutestit riippuvat ulkoisista työkaluista, kuten `rg`, `grep` ja `sg`, mutta Greph itse ei tarvitse niitä toimiakseen. Rinnakkaiset skannaukset käyttävät `ext-pcntl`-toimintoa, kun se on saatavilla, ja siirtyvät ongelmitta yhden prosessin suoritukseen, jos se puuttuu. Isäntäympäristöt, joissa `proc_open()` ja `shell_exec()` on estetty, käsitellään kohdassa [Prosessirajoitetut isännät](https://greph.inline0.dev/fi/docs/advanced/process-restricted-hosts).

## Pikaesimerkki

`vendor/bin`-suoritettavat tiedostot edellyttävät Greph-versiota 0.2.3 tai uudempaa, kun Greph asennetaan projektisi riippuvuutena.

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

Aloita kohdasta [Aloitus](https://greph.inline0.dev/fi/docs/getting-started) ja tutustu sitten rajapinnan muihin osiin kohdissa [CLI](https://greph.inline0.dev/fi/docs/cli) ja [API](https://greph.inline0.dev/fi/docs/api). Osioissa [Tilat](https://greph.inline0.dev/fi/docs/modes/text), [Indeksointi](https://greph.inline0.dev/fi/docs/indexed/text) ja [Yhteensopivuus](https://greph.inline0.dev/fi/docs/compatibility/rg) käsitellään tiettyjä työnkulkuja yksityiskohtaisesti.