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.

Contoh singkat

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

# 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

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, lalu gunakan CLI dan API untuk mempelajari cakupan lainnya. Bagian Mode, Terindeks, dan Kompatibilitas membahas alur kerja tertentu secara mendalam.