Lewati ke konten

Memulai

Lihat sebagai Markdown Edit di GitHub Dokumentasi di d105217

Instalasi

Pasang Greph melalui Composer:

Shell
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:

Shell
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), 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 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:

Shell
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.

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

Shell
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:

Shell
# 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 untuk sintaks pola lengkap.

Penulisan ulang pertama Anda

Tambahkan -r untuk mengubah pencarian AST menjadi penulisan ulang:

Shell
# 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 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.

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

Shell
# 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:

Shell
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

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

Shell
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:

Shell
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:

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

Lihat Terindeks / Teks dan Terindeks / 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:

Shell
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 dan Kompatibilitas / sg, serta disajikan kembali dalam matriks fitur 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.