# Darba sākšana

## Instalēšana

Instalējiet Greph, izmantojot Composer:

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

Tiek instalēta bibliotēka un četras izpildāmās programmas mapē `vendor/bin/`:

- `greph`: vietējā teksta meklēšana, AST meklēšana un AST pārrakstīšana
- `greph-index`: uzsildīts teksta indekss, AST faktu indekss un kešota AST meklēšana
- `rg`: ar ripgrep saderīgs wrapper
- `sg`: ar ast-grep saderīgs wrapper

Šīs izpildāmās programmas darbojas no jūsu projekta `vendor/bin/`, jo Greph 0.2.3. Iepriekšējie laidieni atrada Composer automātiskās ielādes failu tikai Greph repozitorija klonā, tāpēc nepieciešama vismaz šī versija:

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

## Prasības

- **PHP 8.2+** tikai lasāmām klasēm, enum tipiem, pirmšķirīgai izsaucamo funkciju sintaksei un konstruktoru parametru paaugstināšanai
- **ext-json** JSON izvadei un diskā glabātām indeksa datu kopām
- **ext-ctype** paraugu un opciju parsēšanai
- **ext-tokenizer** PHP-Parser un AST priekšfiltriem
- **ext-zlib** kešotajai AST krātuvei (`greph-index ast-cache`)
- **nikic/php-parser** (tiek instalēts automātiski kā Composer atkarība)

`ext-json`, `ext-ctype` un `ext-tokenizer` ir iespējoti gandrīz katrā PHP būvējumā. `composer.json` pašlaik deklarē tikai `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), tāpēc Composer nebrīdina, ja trūkst kāda no pārējiem paplašinājumiem.

Pēc izvēles:

- **ext-pcntl** paralēlai skenēšanai. Ja tā trūkst, Greph bez problēmām pārslēdzas uz viena procesa izpildi.
- Ārējie `rg`, `grep` un `sg` binārie faili salīdzināšanai etalonpārbaudēs. Tie nekad nav nepieciešami darbības laikā.

Meklēšana, pārrakstīšana un indeksēšana nekad neizsauc `proc_open()` vai `shell_exec()`; tiek izveidoti atvasināti procesi tikai paralēlās skenēšanas laikā, un bez `pcntl_fork()` tā pārslēdzas uz viena procesa režīmu. Par resursdatoriem, kas atspējo `proc_open()`, `shell_exec()` vai `pcntl_fork()`, skatiet sadaļu [Procesiem ierobežotas vides](https://greph.inline0.dev/lv/docs/advanced/process-restricted-hosts).

## Pirmā teksta meklēšana

Greph noklusējuma režīms ir ar grep saderīga teksta meklēšana:

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

Izvade izmanto kanonisko `file:line:content` formātu, ko sagaida grep, ripgrep un lielākā daļa redaktoru integrāciju.

```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(
```

Pievienojiet `-i` reģistrnejutīgai atbilstībai, `-w` pilnu vārdu atbilstībai, `-c` atrasto gadījumu skaitam, `-l` tikai failu ceļiem, `-C 2` divām konteksta rindām un tā tālāk. Pilns saraksts ir atrodams [atsauces rokasgrāmatāCLI](https://greph.inline0.dev/lv/docs/cli).

## Pirmā AST meklēšana

Lai pārslēgtos uz strukturālo meklēšanu, norādiet `-p` un PHP formas paraugu:

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

`$CLASS` ir metamainīgais, kas uztver jebkuru klases nosaukumu. Paraugs `new $CLASS()` atbilst katrai `new` izteiksmei bez argumentiem neatkarīgi no klases, formatējuma vai komentāriem. Lai atrastu izsaukumus ar jebkādiem argumentiem, izmantojiet `new $CLASS($$$ARGS)`.

Katra AST atbilstība tiek izvadīta kā fails, sākuma rinda un atbilstošais kods:

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

Citi noderīgi paraugi:

```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
```

Pilnu paraugu sintaksi skatiet sadaļā [Režīmi / AST meklēšana](https://greph.inline0.dev/lv/docs/modes/ast).

## Pirmā pārrakstīšana

Pievienojiet `-r`, lai AST meklēšanu pārvērstu par pārrakstīšanu:

```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
```

Ārpus atbilstības vietas pārrakstīšana saglabā formatējumu: tiek aizstāts tikai atbilstošais mezgls, bet apkārtējās atstarpes, atkāpes un komentāri paliek neskarti. Pats atbilstošais mezgls tiek izvadīts no jauna, izmantojot veidni, tāpēc tā izkārtojums tiek normalizēts un tajā ievietots komentārs var pazust. Plašāku informāciju skatiet sadaļā [Režīmi / pārrakstīšana](https://greph.inline0.dev/lv/docs/modes/rewrite).

## PHP API

Statiskā `Greph\Greph` fasāde nodrošina tādas pašas darbības kā 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";
}
```

Visa funkcionalitāte ir aprakstīta sadaļā [API](https://greph.inline0.dev/lv/docs/api).

## Indeksētā meklēšana

Atkārtotām slodzēm noder uzsildīti indeksi. Izveidojiet indeksu vienreiz un pēc tam veiciet daudz vaicājumu:

```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
```

Pēc noklusējuma indeksi projekta saknes mapē tiek glabāti mapēs `.greph-index`, `.greph-ast-index` un `.greph-ast-cache`.

Bieži mainīgām koda kokstruktūrām izvēlieties dzīves cikla profilu, nevis visiem uzsildītajiem indeksiem izmantojiet vienādu pieeju:

```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
```

Parasti to dara šādi:

- uzturiet stabilu pamatstāvokli kā `static`
- uzturiet aktīvi mainīgus pārklājumus kā `opportunistic-refresh`
- pārbaudiet novecojušu datu uzvedību ar `stats --dry-refresh`

### Vairāku indeksu uzsildītā meklēšana

Vienā komandā varat meklēt vairākos uzsildītos indeksos:

```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
```

### Nosauktas indeksu kopas

Ja to darāt atkārtoti, saglabājiet izkārtojumu `.greph-index-set.json` un indeksu kopu apakškomandas izmantojiet karodziņu atkārtotas norādīšanas vietā:

```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)' .
```

### Plānotāja izsekošana

Lai redzētu, kā uzsildītā meklēšana sašaurina kandidātu loku, pievienojiet `--trace-plan`:

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

Pilnu uzsildīto darbplūsmu skatiet sadaļās [Indeksētais / teksts](https://greph.inline0.dev/lv/docs/indexed/text) un [Indeksētais / AST](https://greph.inline0.dev/lv/docs/indexed/ast).

## Saderības wrapperi

Ja jums ir rīki vai aģenti, kas jau izmanto ripgrep vai ast-grep, pievienojiet wrapperus:

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

Abi wrapperi atkārtoti izmanto vienu un to pašu dzini, un to atbilstība upstream binārajiem failiem ir pārbaudīta ar zondēm. Pārbaudītā funkcionalitāte ir dokumentēta sadaļās [Saderība / rg](https://greph.inline0.dev/lv/docs/compatibility/rg) un [Saderība / sg](https://greph.inline0.dev/lv/docs/compatibility/sg), kā arī atspoguļota ģenerētajā [funkciju matricā](https://greph.inline0.dev/lv/docs/advanced/feature-matrix).

## Konfigurācija

Greph atpazīst divas diskā izmantotas konvencijas:

- `.gitignore`: tiek ievērota pēc noklusējuma. Lai atspējotu, norādiet `--no-ignore`.
- `.grephignore`: tāda pati sintakse kā `.gitignore`, tiek lietota papildus. Noder rīkiem specifiskiem izņēmumiem, kurus nevēlaties iekļaut versiju vadībā.

Noklusētās indeksu mapes izvēlētajā saknes mapē ir `.greph-index`, `.greph-ast-index` un `.greph-ast-cache`. Pārrakstiet tās ar `--index-dir` jebkurā `greph-index` apakškomandā vai izmantojiet `.greph-index-set.json` atkārtojamiem vairāku indeksu izkārtojumiem.