# Darbo pradžia

## Diegimas

Įdiekite Greph naudodami Composer:

```bash
composer require greph/greph
```

Taip `vendor/bin/` įdiegiama biblioteka ir keturi vykdomieji failai:

- `greph`: vietinė tekstinė paieška, AST paieška ir AST perrašymas
- `greph-index`: įšildytas tekstinis indeksas, AST faktų indeksas ir spartinančioji AST paieška
- `rg`: ripgrep stiliaus suderinamumo apvalkalas
- `sg`: ast-grep stiliaus suderinamumo apvalkalas

Šie vykdomieji failai veikia iš jūsų projekto `vendor/bin/`, nes Greph 0.2.3. Ankstesnės versijos Composer įkėliklį rasdavo tik Greph saugyklos klone, todėl reikalinga bent ši versija:

```bash
composer require greph/greph:^0.2.3
```

## Reikalavimai

- **PHP 8.2+** readonly klasėms, enum tipams, pirmos klasės iškviečiamų funkcijų sintaksei ir konstruktoriaus savybių propagavimui
- **ext-json** JSON išvestims ir diske saugomiems indeksų duomenims
- **ext-ctype** šablonų ir parinkčių analizei
- **ext-tokenizer** PHP-Parser ir AST išankstiniams filtrams
- **ext-zlib** podėlyje saugomai AST saugyklai (`greph-index ast-cache`)
- **nikic/php-parser** (automatiškai įdiegiama kaip Composer priklausomybė)

`ext-json`, `ext-ctype` ir `ext-tokenizer` įjungti beveik kiekvienoje PHP versijoje. Šiuo metu `composer.json` deklaruoja tik `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), todėl Composer neįspėja, jei trūksta kurio nors kito plėtinio.

Pasirenkama:

- **ext-pcntl** lygiagrečioms paieškoms. Jei jo nėra, Greph sklandžiai pereina prie vykdymo viename procese.
- Išoriniai `rg`, `grep` ir `sg` dvejetainiai failai palyginimams su etalonais. Vykdymo metu jų niekada nereikia.

Paieška, perrašymas ir indeksavimas niekada nekviečia `proc_open()` ar `shell_exec()`; tik lygiagrečios paieškos sukuria atskirus procesus, o be `pcntl_fork()` jos grįžta prie vieno proceso. Apie prieglobos serverius, kuriuose išjungti `proc_open()`, `shell_exec()` arba `pcntl_fork()`, žr. [Procesais apribotos prieglobos aplinkos](https://greph.inline0.dev/lt/docs/advanced/process-restricted-hosts).

## Pirmoji teksto paieška

Numatytasis Greph režimas – su grep suderinama teksto paieška:

```bash
vendor/bin/greph -F "function" src
```

Išvestis pateikiama kanoniniu `file:line:content` formatu, kurio tikisi grep, ripgrep ir dauguma redaktorių integracijų.

```text
src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(
```

Pridėkite `-i`, kad paieška neskirtų didžiųjų ir mažųjų raidžių, `-w`, kad būtų ieškoma ištisų žodžių, `-c`, kad būtų rodomi atitikmenų skaičiai, `-l`, kad būtų ieškoma tik failų keliuose, `-C 2`, kad būtų rodomos dvi konteksto eilutės ir pan. Visas sąrašas pateiktas [CLI nuorodoje](https://greph.inline0.dev/lt/docs/cli).

## Pirmoji AST paieška

Norėdami įjungti struktūrinę paiešką, perduokite `-p` ir PHP formos šabloną:

```bash
vendor/bin/greph -p 'new $CLASS()' src
```

`$CLASS` yra metakintamasis, atitinkantis bet kurį klasės pavadinimą. Šablonas `new $CLASS()` atitinka kiekvieną `new` išraišką be argumentų, nepriklausomai nuo klasės, formatavimo ar komentarų. Naudokite `new $CLASS($$$ARGS)`, jei norite atitikti iškvietimus su bet kokiais argumentais.

Kiekviena AST atitiktis išvedama kaip failas, pradžios eilutė ir atitinkantis kodas:

```text
src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()
```

Kiti naudingi šablonai:

```bash
# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src

# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src
```

Visą šablonų sintaksę rasite skiltyje [Režimai / AST paieška](https://greph.inline0.dev/lt/docs/modes/ast).

## Pirmasis perrašymas

Pridėkite `-r`, kad AST paiešką paverstumėte perrašymu:

```bash
# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

Už atitikties ribų perrašymai išsaugo formatavimą: pakeičiamas tik atitinkantis mazgas, o aplinkiniai tarpai, įtraukos ir komentarai lieka nepakeisti. Pats atitinkantis mazgas iš naujo sugeneruojamas pagal šabloną, todėl jo išdėstymas normalizuojamas, o jame esantis komentaras gali būti prarastas. Daugiau informacijos rasite skiltyje [Režimai / Perrašymas](https://greph.inline0.dev/lt/docs/modes/rewrite).

## PHP API

Statinė `Greph\Greph` fasadinė sąsaja pateikia tas pačias operacijas kaip ir CLI:

```php
use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}
```

Visas funkcijas apima [API](https://greph.inline0.dev/lt/docs/api).

## Indeksuota paieška

Pasikartojančios užduotys greičiau atliekamos naudojant įkeltus indeksus. Sukurkite indeksą vieną kartą, tada vykdykite daug užklausų:

```bash
# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src
```

Pagal numatytuosius nustatymus indeksai projekto šakiniame kataloge saugomi `.greph-index`, `.greph-ast-index` ir `.greph-ast-cache`.

Aktyviai kintančiam kodui pasirinkite gyvavimo ciklo profilį, užuot visiems įkeltiems indeksams taikę tą patį režimą:

```bash
vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh
```

Dažniausiai naudojamas šablonas:

- stabilų pagrindą laikykite kaip `static`
- aktyviai kintančius perdengimus laikykite kaip `opportunistic-refresh`
- pasenusią būseną tikrinkite naudodami `stats --dry-refresh`

### Paieška keliuose įkeltuose indeksuose

Viena komanda galite ieškoti keliuose įkeltuose indeksuose:

```bash
vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin
```

### Pavadinti indeksų rinkiniai

Jei tai darote pakartotinai, aprašykite išdėstymą faile `.greph-index-set.json` ir vietoj pakartotinai nurodomų vėliavėlių naudokite rinkinio subkomandas:

```bash
vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .
```

### Planavimo pėdsakas

Norėdami matyti, kaip įkelta paieška susiaurina kandidatų ratą, pridėkite `--trace-plan`:

```bash
vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .
```

Visą įkeltų indeksų darbo eigą rasite skiltyse [Indeksuota / Tekstas](https://greph.inline0.dev/lt/docs/indexed/text) ir [Indeksuota / AST](https://greph.inline0.dev/lt/docs/indexed/ast).

## Suderinamumo apvalkalai

Jei jūsų įrankiai ar agentai jau naudoja ripgrep arba ast-grep, tiesiog įtraukite apvalkalus:

```bash
vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php
```

Abu apvalkalai naudoja tą patį variklį, o jų suderinamumas patikrintas su pirminiais dvejetainiais failais. Patikrintos funkcijos aprašytos skiltyse [Suderinamumas / rg](https://greph.inline0.dev/lt/docs/compatibility/rg) ir [Suderinamumas / sg](https://greph.inline0.dev/lt/docs/compatibility/sg), taip pat pateiktos sugeneruotoje [funkcijų matricoje](https://greph.inline0.dev/lt/docs/advanced/feature-matrix).

## Konfigūracija

Greph atpažįsta dvi diske naudojamas konvencijas:

- `.gitignore`: pagal numatytuosius nustatymus paisoma. Norėdami išjungti, perduokite `--no-ignore`.
- `.grephignore`: ta pati sintaksė kaip `.gitignore`, taikoma papildomai. Naudinga įrankiui būdingoms išimtims, kurių nenorite įtraukti į versijų kontrolę.

Pasirinktame šakniniame kataloge numatytieji indeksų katalogai yra `.greph-index`, `.greph-ast-index` ir `.greph-ast-cache`. Bet kurioje `greph-index` subkomandoje nurodykite kitą katalogą naudodami `--index-dir` arba naudokite `.greph-index-set.json`, jei reikia pakartotinai naudojamų kelių indeksų išdėstymų.