# Memulai

## Instalasi

Pasang Greph melalui Composer:

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

Ini memasang pustaka beserta empat executable di `vendor/bin/`:

- `greph`: pencarian teks native, pencarian AST, dan penulisan ulang AST
- `greph-index`: indeks teks yang telah dimuat, indeks fakta AST, dan pencarian AST yang di-cache
- `rg`: pembungkus kompatibilitas bergaya ripgrep
- `sg`: pembungkus kompatibilitas bergaya ast-grep

Executable ini bekerja dari `vendor/bin/` proyek Anda karena Greph 0.2.3. Rilis sebelumnya hanya menemukan autoloader Composer di dalam klona repositori Greph, jadi gunakan setidaknya versi tersebut:

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

## Persyaratan

- **PHP 8.2+** untuk kelas readonly, enum, sintaks callable kelas satu, dan promosi konstruktor
- **ext-json** untuk keluaran JSON dan payload indeks di disk
- **ext-ctype** untuk parsing pola dan opsi
- **ext-tokenizer** untuk PHP-Parser dan pra-filter AST
- **ext-zlib** untuk penyimpanan AST yang di-cache (`greph-index ast-cache`)
- **nikic/php-parser** (diinstal otomatis sebagai dependensi Composer)

`ext-json`, `ext-ctype`, dan `ext-tokenizer` tersedia di hampir semua build PHP. `composer.json` saat ini hanya mendeklarasikan `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), jadi Composer tidak memberikan peringatan saat salah satunya tidak tersedia.

Opsional:

- **ext-pcntl** untuk pemindaian paralel. Greph tetap berfungsi dengan baik dalam eksekusi satu proses jika ekstensi ini tidak tersedia.
- Biner `rg`, `grep`, dan `sg` eksternal untuk perbandingan benchmark. Biner ini tidak pernah diperlukan saat runtime.

Pencarian, penulisan ulang, dan pengindeksan tidak pernah memanggil `proc_open()` atau `shell_exec()`; hanya pemindaian paralel yang membuat proses turunan, dan proses tersebut beralih ke satu proses tanpa `pcntl_fork()`. Lihat [Host dengan Pembatasan Proses](https://greph.inline0.dev/id/docs/advanced/process-restricted-hosts) untuk host yang menonaktifkan `proc_open()`, `shell_exec()`, atau `pcntl_fork()`.

## Pencarian teks pertama Anda

Mode default Greph adalah pencarian teks yang kompatibel dengan grep:

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

Output menggunakan format `file:line:content` kanonis yang diharapkan oleh grep, ripgrep, dan sebagian besar integrasi editor.

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

Tambahkan `-i` untuk pencocokan tanpa membedakan huruf besar-kecil, `-w` untuk pencocokan kata utuh, `-c` untuk jumlah, `-l` untuk jalur file saja, `-C 2` untuk dua baris konteks, dan seterusnya. Daftar lengkapnya tersedia di referensi [CLI](https://greph.inline0.dev/id/docs/cli).

## Pencarian AST pertama Anda

Berikan `-p` dan pola berbentuk PHP untuk beralih ke pencarian struktural:

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

`$CLASS` adalah metavariabel yang menangkap nama kelas apa pun. Pola `new $CLASS()` cocok dengan setiap ekspresi `new` tanpa argumen, terlepas dari kelas, pemformatan, atau komentarnya. Gunakan `new $CLASS($$$ARGS)` untuk mencocokkan pemanggilan dengan argumen apa pun.

Setiap kecocokan AST ditampilkan sebagai file, baris awal, dan kode yang cocok:

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

Pola berguna lainnya:

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

Lihat [Mode / Pencarian AST](https://greph.inline0.dev/id/docs/modes/ast) untuk sintaks pola lengkap.

## Penulisan ulang pertama Anda

Tambahkan `-r` untuk mengubah pencarian AST menjadi penulisan ulang:

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

Penulisan ulang mempertahankan format di luar kecocokan: hanya node yang cocok yang diganti, sedangkan spasi, indentasi, dan komentar di sekitarnya tetap utuh. Node yang cocok dicetak ulang dari templat, sehingga tata letaknya dinormalisasi dan komentar di dalamnya bisa hilang. Lihat [Mode / Penulisan Ulang](https://greph.inline0.dev/id/docs/modes/rewrite) untuk detailnya.

## PHP API

Facade statis `Greph\Greph` menyediakan operasi yang sama dengan 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";
}
```

Seluruh cakupannya dibahas di [API](https://greph.inline0.dev/id/docs/api).

## Pencarian terindeks

Beban kerja berulang mendapat manfaat dari indeks yang telah dimuat. Bangun indeks sekali, lalu jalankan kueri berkali-kali:

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

Secara default, indeks disimpan di `.greph-index`, `.greph-ast-index`, dan `.greph-ast-cache` di direktori akar proyek.

Untuk pohon yang terus berubah, pilih profil siklus hidup alih-alih memperlakukan semua indeks yang telah dimuat dengan cara yang sama:

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

Pola umumnya:

- jadikan dasar yang stabil sebagai `static`
- jadikan lapisan yang terus berubah sebagai `opportunistic-refresh`
- periksa perilaku data usang dengan `stats --dry-refresh`

### Pencarian multi-indeks yang telah dimuat

Anda dapat mencari di beberapa indeks yang telah dimuat dengan satu perintah:

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

### Kumpulan indeks bernama

Jika Anda berulang kali melakukan hal tersebut, simpan tata letaknya di `.greph-index-set.json` dan gunakan subperintah set alih-alih mengulang flag:

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

### Jejak perencana

Untuk melihat cara pencarian yang telah dimuat mempersempit kandidat, tambahkan `--trace-plan`:

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

Lihat [Terindeks / Teks](https://greph.inline0.dev/id/docs/indexed/text) dan [Terindeks / AST](https://greph.inline0.dev/id/docs/indexed/ast) untuk alur kerja lengkap dengan indeks yang telah dimuat.

## Pembungkus kompatibilitas

Jika Anda memiliki alat atau agen yang sudah menggunakan ripgrep atau ast-grep, gunakan pembungkus berikut:

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

Kedua pembungkus menggunakan kembali mesin yang sama dan telah diverifikasi melalui probe terhadap biner upstream. Cakupan yang terverifikasi didokumentasikan di [Kompatibilitas / rg](https://greph.inline0.dev/id/docs/compatibility/rg) dan [Kompatibilitas / sg](https://greph.inline0.dev/id/docs/compatibility/sg), serta disajikan kembali dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix) yang dibuat secara otomatis.

## Konfigurasi

Greph mengenali dua konvensi di disk:

- `.gitignore`: diterapkan secara default. Berikan `--no-ignore` untuk menonaktifkannya.
- `.grephignore`: sintaksnya sama dengan `.gitignore` dan diterapkan di atasnya. Berguna untuk pengecualian khusus alat yang tidak ingin Anda simpan dalam kontrol versi.

Direktori indeks default adalah `.greph-index`, `.greph-ast-index`, dan `.greph-ast-cache` di akar yang dipilih. Ganti dengan `--index-dir` pada subperintah `greph-index` apa pun, atau gunakan `.greph-index-set.json` untuk tata letak multi-indeks yang dapat digunakan berulang kali.