# Pendahuluan
Greph adalah mesin pencarian dan pemfaktoran ulang PHP murni untuk pohon kode sumber. Mesin ini mencakup tiga mode terkait:

- **Pencarian teks** dengan output yang kompatibel dengan grep dan kemudahan penggunaan bergaya ripgrep.
- **Pencarian AST** dengan pola struktural PHP dan metavariabel.
- **Penulisan ulang AST** untuk pemfaktoran ulang struktural yang mempertahankan format.

Produk ini juga menyediakan mode terindeks dengan indeks yang telah dimuat untuk beban kerja teks dan AST, kebijakan penyegaran yang mengikuti siklus hidup, kumpulan indeks yang telah dimuat berbasis manifes, serta pembungkus kompatibilitas `rg` / `sg` untuk lingkungan alat dan agen.

## Alasan Greph dibuat

Aplikasi dan agen PHP yang membutuhkan pencarian kode cepat biasanya menjalankan alat native melalui shell (`grep`, `ripgrep`, `ast-grep`), sehingga mengorbankan portabilitas dan menambah kendala penerapan. Pencarian dan penulisan ulang struktural bahkan lebih sulit: biasanya proses PHP harus ditinggalkan sepenuhnya.

Greph mengatasi kesenjangan itu. Kode PHP Anda dapat menjalankan pencarian teks, mencocokkan struktur, dan menulis ulang hasil pemfaktoran ulang hanya dengan pustaka standar ditambah `nikic/php-parser`. Output dan kode keluar kompatibel dengan alat kanonis, sehingga skrip dan agen yang ada tidak perlu diubah.

## Fungsinya

- Pencarian teks dengan string tetap dan regex, serta mode kata utuh, tanpa membedakan huruf besar-kecil, konteks, jumlah, dan file saja
- Pencarian AST struktural PHP dengan `$VAR`, `$$$VARIADIC`, dan metavariabel berulang
- Penulisan ulang AST yang mempertahankan format dengan mode uji coba, interaktif, dan tulis
- Indeks teks yang telah dimuat (trigram + posting identifier) untuk beban kerja berulang
- Indeks fakta AST yang telah dimuat dan pencarian AST yang di-cache untuk kueri struktural berulang
- Indeks yang telah dimuat dengan siklus hidup yang diperhatikan: `static`, `manual-refresh`, `opportunistic-refresh`, `strict-stale-check`
- Pencarian multi-indeks dan set bernama di penyimpanan teks, fakta AST, dan cache AST yang telah dimuat
- Diagnostik perencana dengan `--trace-plan` dan pelabelan asal indeks untuk pencarian yang telah dimuat
- Pembungkus kompatibilitas ripgrep dan ast-grep CLI yang menggunakan mesin yang sama
- Kumpulan pekerja paralel berbasis pcntl dengan cadangan satu proses
- Penjelajah file yang memperhatikan gitignore dan `.grephignore` serta mendeteksi file biner

## Persyaratan

- PHP 8.2 atau lebih baru
- `ext-json`, `ext-ctype`, dan `ext-tokenizer`, yang tersedia di hampir semua build PHP
- `ext-zlib` untuk penyimpanan AST yang di-cache (`greph-index ast-cache`)
- `nikic/php-parser` (satu-satunya dependensi Composer)

Fitur inti teks dan AST berjalan dalam PHP murni. Perbandingan benchmark opsional bergantung pada alat eksternal seperti `rg`, `grep`, dan `sg`, tetapi Greph sendiri tidak membutuhkannya untuk beroperasi. Pemindaian paralel menggunakan `ext-pcntl` jika tersedia dan beralih dengan baik ke eksekusi satu proses jika tidak. Host yang melarang `proc_open()` dan `shell_exec()` dibahas di [Host dengan Pembatasan Proses](https://greph.inline0.dev/id/docs/advanced/process-restricted-hosts).

## Contoh singkat

Executable `vendor/bin` memerlukan Greph 0.2.3 atau lebih baru ketika Greph dipasang sebagai dependensi proyek Anda.

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

Mulailah dengan [Memulai](https://greph.inline0.dev/id/docs/getting-started), lalu gunakan [CLI](https://greph.inline0.dev/id/docs/cli) dan [API](https://greph.inline0.dev/id/docs/api) untuk mempelajari cakupan lainnya. Bagian [Mode](https://greph.inline0.dev/id/docs/modes/text), [Terindeks](https://greph.inline0.dev/id/docs/indexed/text), dan [Kompatibilitas](https://greph.inline0.dev/id/docs/compatibility/rg) membahas alur kerja tertentu secara mendalam.