# Začetek

## Namestitev

Namestite Greph prek Composer:

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

S tem namestite knjižnico in štiri izvršne datoteke v `vendor/bin/`:

- `greph`: iskanje po besedilu, iskanje po AST in prepis AST
- `greph-index`: ogret besedilni indeks, indeks dejstev AST in predpomnjeno iskanje po AST
- `rg`: ovojnica za združljivost v slogu ripgrep
- `sg`: ovojnica za združljivost v slogu ast-grep

Te izvršne datoteke delujejo iz `vendor/bin/` vašega projekta, saj Greph 0.2.3. Starejše izdaje so nalagalnik Composer našle le znotraj klona repozitorija Greph, zato uporabite vsaj to različico:

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

## Zahteve

- **PHP 8.2+** za razrede samo za branje, naštevanja, sintakso klicevnih izrazov prvega razreda in promocijo konstruktorjev
- **ext-json** za izhod JSON in podatke koristnega tovora indeksov na disku
- **ext-ctype** za razčlenjevanje vzorcev in možnosti
- **ext-tokenizer** za PHP-Parser in predfiltre AST
- **ext-zlib** za shrambo predpomnjenega AST (`greph-index ast-cache`)
- **nikic/php-parser** (samodejno nameščen kot odvisnost Composer)

`ext-json`, `ext-ctype` in `ext-tokenizer` so omogočeni v skoraj vsaki gradnji PHP. `composer.json` trenutno navaja samo `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), zato Composer ne opozori, če kateri od drugih manjka.

Izbirno:

- **ext-pcntl** za vzporedna pregledovanja. Greph ob njegovi odsotnosti nemoteno preklopi na izvajanje v enem procesu.
- Zunanje binarne datoteke `rg`, `grep` in `sg` za primerjave zmogljivosti. Za izvajanje nikoli niso potrebne.

Iskanje, prepisovanje in indeksiranje nikoli ne kličejo `proc_open()` ali `shell_exec()`; samo vzporedna pregledovanja ustvarijo podrejene procese, brez `pcntl_fork()` pa se vrnejo na en sam proces. Za gostitelje, ki onemogočajo `proc_open()`, `shell_exec()` ali `pcntl_fork()`, glejte [Gostitelji z omejenimi procesi](https://greph.inline0.dev/sl/docs/advanced/process-restricted-hosts).

## Vaše prvo iskanje po besedilu

Privzeti način Greph je iskanje po besedilu, združljivo z grep:

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

Izhod uporablja kanonično obliko `file:line:content`, ki jo pričakujejo grep, ripgrep in večina integracij urejevalnikov.

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

Dodajte `-i` za ujemanje brez razlikovanja med velikimi in malimi črkami, `-w` za ujemanje celih besed, `-c` za štetje, `-l` samo za poti datotek, `-C 2` za dve vrstici konteksta in tako naprej. Celoten seznam je v referenci [CLI](https://greph.inline0.dev/sl/docs/cli).

## Vaše prvo iskanje po AST

Podajte `-p` in vzorec v obliki PHP, da preklopite na strukturno iskanje:

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

`$CLASS` je metaspremenljivka, ki zajame poljubno ime razreda. Vzorec `new $CLASS()` ustreza vsakemu izrazu `new` brez argumentov, ne glede na razred, oblikovanje ali komentarje. Za ujemanje klicev s poljubnimi argumenti uporabite `new $CLASS($$$ARGS)`.

Vsako ujemanje AST je izpisano kot datoteka, začetna vrstica in ujemajoča se koda:

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

Drugi uporabni vzorci:

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

Za celotno sintakso vzorcev glejte [Načini / iskanje AST](https://greph.inline0.dev/sl/docs/modes/ast).

## Vaš prvi prepis

Dodajte `-r`, da iskanje AST spremenite v prepis:

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

Pri prepisih se oblikovanje zunaj ujemanja ohrani: zamenja se samo ujemajoče se vozlišče, okoliški presledki, zamiki in komentarji pa ostanejo nedotaknjeni. Ujemajoče se vozlišče se na novo izpiše iz predloge, zato se njegova lastna postavitev poenoti, komentar v njem pa se lahko izgubi. Več podrobnosti najdete v [Načini / prepis](https://greph.inline0.dev/sl/docs/modes/rewrite).

## PHP API

Statični fasadni vmesnik `Greph\Greph` izpostavlja enake operacije kot 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";
}
```

Celoten nabor je opisan v [API](https://greph.inline0.dev/sl/docs/api).

## Indeksirano iskanje

Pri ponavljajočih se opravilih pomagajo ogreti indeksi. Zgradite jih enkrat, nato poizvedujte večkrat:

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

Indeksi so privzeto shranjeni v `.greph-index`, `.greph-ast-index` in `.greph-ast-cache` v korenski mapi projekta.

Pri drevesih, ki se aktivno spreminjajo, izberite profil življenjskega cikla, namesto da bi vse ogrete indekse obravnavali enako:

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

Običajen vzorec je:

- ohranite stabilno osnovo kot `static`
- ohranite aktivno spreminjajoče se nadgradnje kot `opportunistic-refresh`
- vedenje zastarelih indeksov preverjajte z `stats --dry-refresh`

### Iskanje v več ogretih indeksih

V enem ukazu lahko iščete po več ogretih indeksih:

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

### Poimenovani nabori indeksov

Če to počnete večkrat, shranite razporeditev v `.greph-index-set.json` in uporabite podukaze za nabore, namesto da ponavljate zastavice:

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

### Sled načrtovalnika

Če želite videti, kako ogreto iskanje zoži nabor kandidatov, dodajte `--trace-plan`:

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

Za celoten potek dela z ogretimi indeksi glejte [Indeksirano / besedilo](https://greph.inline0.dev/sl/docs/indexed/text) in [Indeksirano / AST](https://greph.inline0.dev/sl/docs/indexed/ast).

## Ovojnice za združljivost

Če vaša orodja ali agenti že uporabljajo ripgrep ali ast-grep, preprosto uporabite ovojnice:

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

Obe ovojnici znova uporabljata isti mehanizem in sta preverjeni s preizkusnimi ukazi glede na izvorni binarni datoteki. Preverjeni nabor je dokumentiran v [Združljivost / rg](https://greph.inline0.dev/sl/docs/compatibility/rg) in [Združljivost / sg](https://greph.inline0.dev/sl/docs/compatibility/sg) ter ponovljen v ustvarjeni [matriki funkcij](https://greph.inline0.dev/sl/docs/advanced/feature-matrix).

## Konfiguracija

Greph upošteva dve dogovorni ureditvi na disku:

- `.gitignore`: privzeto se upošteva. Podajte `--no-ignore`, če želite to izklopiti.
- `.grephignore`: enaka sintaksa kot pri `.gitignore`, uporabljena dodatno. Uporabno za izključitve, specifične za orodje, ki jih ne želite vključiti v nadzor različic.

Privzeti imeniki indeksov so `.greph-index`, `.greph-ast-index` in `.greph-ast-cache` v izbrani korenski mapi. Preglasite jih z `--index-dir` pri katerem koli podukazu `greph-index` ali uporabite `.greph-index-set.json` za ponovljive razporeditve z več indeksi.