PHP API

Lihat sebagai Markdown Edit di GitHub Dokumentasi di d105217

`Greph\Greph`

Kelas Greph\Greph adalah titik masuk statis. Kelas ini menyediakan semua operasi pencarian, penulisan ulang, dan pengindeksan. Semua metode menerima satu jalur atau daftar jalur.

PHP

use Greph\Greph;

`walk`

PHP

public static function walk(string|array $paths, ?WalkOptions $options = null): FileList

Uraikan $paths menjadi FileList datar berisi jalur file absolut. Mengikuti gitignore, .grephignore, filter tipe file, pola glob, penyertaan file tersembunyi, penelusuran symlink, deteksi biner, dan batas ukuran file maksimum.

PHP

use Greph\Walker\WalkOptions;
use Greph\Walker\FileTypeFilter;

$files = Greph::walk('src', new WalkOptions(
    fileTypeFilter: new FileTypeFilter(['php']),
));

foreach ($files->paths() as $path) {
    echo "$path\n";
}

`searchText`

PHP

public static function searchText(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
): array

Jalankan pencarian teks dan kembalikan list<TextFileResult>. Setiap TextFileResult menyediakan jalur file dan daftar objek TextMatch (baris, kolom, konten, tangkapan, konteks opsional).

PHP

use Greph\Greph;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(
        fixedString: true,
        caseInsensitive: true,
        beforeContext: 1,
        afterContext: 1,
        jobs: 4,
    ),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

Saat jobs > 1 dan jumlah file melampaui ambang pekerja, searchText otomatis mengirim pemindaian ke WorkerPool. Jika tidak, pemindaian berjalan dalam proses yang sama.

`searchAst`

PHP

public static function searchAst(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

Jalankan pencarian AST struktural dan kembalikan list<AstMatch>. Pola ditulis sebagai sumber PHP dengan metavariabel $VAR dan $$$VARIADIC. Setiap AstMatch mencakup file, PhpParser\Node yang ditangkap, tangkapan, baris awal/akhir dan offset byte, serta irisan sumber yang cocok.

PHP

use Greph\Greph;
use Greph\Ast\AstSearchOptions;

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

`rewriteAst`

PHP

public static function rewriteAst(
    string $searchPattern,
    string $rewritePattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
): array

Jalankan penulisan ulang struktural dan kembalikan list<RewriteResult>. Setiap RewriteResult menyediakan jalur file, konten asli, konten hasil penulisan ulang, dan jumlah penggantian. Penulisan ulang mempertahankan format: hanya rentang node yang cocok yang disisipkan; bagian file lainnya tidak disentuh.

PHP

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);

foreach ($rewrites as $result) {
    if ($result->changed()) {
        file_put_contents($result->file, $result->rewrittenContents);
    }
}

Facade tidak menulis ke disk; pemanggil menentukan apakah perubahan diterapkan. CLI menerapkannya kecuali jika --dry-run atau --interactive ditetapkan.

Pencarian teks terindeks

`buildTextIndex`

PHP

public static function buildTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

Buat indeks trigram dan postings pengenal baru untuk $rootPath. Indeks disimpan di $indexPath (default $rootPath/.greph-index). $lifecycle dapat berupa static, manual-refresh, opportunistic-refresh, atau strict-stale-check. Mengembalikan IndexBuildResult yang berisi jumlah file, jumlah trigram, serta jumlah yang ditambahkan/diperbarui/dihapus/tidak berubah.

`refreshTextIndex`

PHP

public static function refreshTextIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): IndexBuildResult

Perbarui indeks teks yang ada secara bertahap. File di-hash ulang dan hanya entri yang berubah yang ditulis ulang.

`searchTextIndexed`

PHP

public static function searchTextIndexed(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $indexPath = null,
): array

Jalankan pencarian teks pada indeks yang sudah dipanaskan. Menghasilkan error runtime jika indeks tidak ada (panggil buildTextIndex terlebih dahulu). Mengembalikan list<TextFileResult> dengan bentuk yang persis sama seperti searchText.

PHP

Greph::buildTextIndex('.');
$results = Greph::searchTextIndexed('function', 'src');

`searchTextIndexedMany`

PHP

public static function searchTextIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?TextSearchOptions $options = null,
): array

Jalankan pencarian teks pada beberapa direktori indeks teks yang sudah dipanaskan. Greph mencari di setiap indeks yang sesuai, menghapus duplikat berdasarkan jalur file absolut, dan menggunakan pemindaian native hanya untuk jalur di luar semua root indeks yang diberikan.

`loadIndexSet`

PHP

public static function loadIndexSet(?string $manifestPath = null): IndexSet

Muat manifes kumpulan indeks, dengan default .greph-index-set.json di direktori kerja saat ini.

`searchTextIndexedSet`

PHP

public static function searchTextIndexedSet(
    string $pattern,
    string|array $paths,
    ?TextSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Uraikan entri text yang dipilih dari manifes kumpulan indeks, lalu jalankan proses yang setara dengan searchTextIndexedMany.

Pencarian AST terindeks

`buildAstIndex` / `refreshAstIndex`

PHP

public static function buildAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult
public static function refreshAstIndex(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstIndexBuildResult

Buat atau perbarui indeks fakta AST secara bertahap. Secara default, fakta yang diekstrak disimpan di $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

public static function searchAstIndexed(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

Gunakan indeks fakta untuk mempersempit kandidat sebelum memverifikasi ulang kecocokan terhadap sumber. Mengembalikan bentuk list<AstMatch> yang sama seperti searchAst.

`searchAstIndexedMany`

PHP

public static function searchAstIndexedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

Jalankan pencarian fakta AST pada beberapa direktori indeks AST yang sudah dipanaskan.

`searchAstIndexedSet`

PHP

public static function searchAstIndexedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Uraikan entri ast-index yang dipilih dari manifes kumpulan indeks, lalu jalankan proses yang setara dengan searchAstIndexedMany.

`buildAstCache` / `refreshAstCache`

PHP

public static function buildAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult
public static function refreshAstCache(
    string $rootPath = '.',
    ?string $indexPath = null,
    IndexLifecycle|IndexLifecycleProfile|string|null $lifecycle = null,
): AstCacheBuildResult

Buat atau perbarui penyimpanan pohon hasil parsing yang di-cache secara bertahap. Secara default, pohon berserialisasi disimpan di $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

public static function searchAstCached(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $indexPath = null,
): array

Jalankan pencarian AST pada pohon hasil parsing yang di-cache, tanpa menjalankan parser sama sekali. Mengembalikan bentuk list<AstMatch> yang sama seperti searchAst.

`searchAstCachedMany`

PHP

public static function searchAstCachedMany(
    string $pattern,
    string|array $paths,
    array $indexPaths,
    ?AstSearchOptions $options = null,
): array

Jalankan pencarian AST dalam cache pada beberapa direktori cache.

`searchAstCachedSet`

PHP

public static function searchAstCachedSet(
    string $pattern,
    string|array $paths,
    ?AstSearchOptions $options = null,
    ?string $manifestPath = null,
    array $entryNames = [],
): array

Uraikan entri ast-cache yang dipilih dari manifes kumpulan indeks, lalu jalankan proses yang setara dengan searchAstCachedMany.

`Greph\Text\TextSearchOptions`

Objek opsi readonly untuk pencarian teks.

PHP

new TextSearchOptions(
    bool $fixedString = false,
    bool $caseInsensitive = false,
    bool $wholeWord = false,
    bool $invertMatch = false,
    ?int $maxCount = null,
    int $beforeContext = 0,
    int $afterContext = 0,
    bool $countOnly = false,
    bool $filesWithMatches = false,
    bool $filesWithoutMatches = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $showLineNumbers = true,
    bool $showFileNames = true,
)

Validasi:

jobs >= 1
beforeContext, afterContext >= 0
maxCount === null || maxCount >= 1

Gunakan walkOptions() untuk mendapatkan WalkOptions yang cocok jika Anda ingin menelusuri pohon file secara terpisah.

tracePlan digunakan oleh pencari terindeks yang sudah dipanaskan dan alur greph-index CLI untuk mengeluarkan diagnostik perencana ke stderr. searchText native sendiri tidak menggunakannya.

`Greph\Ast\AstSearchOptions`

Objek opsi readonly untuk pencarian dan penulisan ulang AST.

PHP

new AstSearchOptions(
    string $language = 'php',
    int $jobs = 1,
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = true,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
    bool $skipParseErrors = true,
    bool $dryRun = false,
    bool $interactive = false,
    bool $jsonOutput = false,
    bool $tracePlan = false,
)

Filter tipe file default untuk mode AST adalah php. Saat skipParseErrors bernilai true (default), file yang gagal diparse akan dilewati tanpa pemberitahuan; ubah ke false untuk menampilkan kesalahan parse sebagai exception. tracePlan digunakan oleh pencari AST yang telah dipanaskan dan greph-index ast-index|ast-cache search untuk menghasilkan diagnostik pemangkasan kandidat.

`Greph\Walker\WalkOptions`

Objek opsi readonly untuk penelusur file.

PHP

new WalkOptions(
    bool $respectIgnore = true,
    bool $includeHidden = false,
    bool $followSymlinks = false,
    bool $skipBinaryFiles = false,
    bool $includeGitDirectory = false,
    ?FileTypeFilter $fileTypeFilter = null,
    int $maxFileSizeBytes = 10485760,
    array $globPatterns = [],
)

`Greph\Walker\FileTypeFilter`

Ubah tipe file bernama menjadi daftar ekstensi. Alias bawaan:

Alias	Ekstensi
`css`	`css`, `sass`, `scss`
`html`	`htm`, `html`, `phtml`
`js`	`cjs`, `js`, `mjs`
`json`	`json`
`md`	`markdown`, `md`
`php`	`inc`, `php`, `php3`, `php4`, `php5`, `php7`, `php8`, `phpt`, `phtml`
`txt`	`txt`
`ts`	`ts`, `tsx`
`xml`	`xml`
`yaml`	`yaml`, `yml`

PHP

new FileTypeFilter(includeTypes: ['php'], excludeTypes: ['md']);

Objek hasil

`Greph\Text\TextFileResult`

PHP

final readonly class TextFileResult
{
    public string $file;
    /** @var list<TextMatch> */
    public array $matches;

    public function matchCount(): int;
    public function hasMatches(): bool;
}

`Greph\Text\TextMatch`

PHP

final readonly class TextMatch
{
    public string $file;
    public int $line;
    public int $column;
    public string $content;
    public string $matchedText;
    /** @var array<int|string, string> */
    public array $captures;
    /** @var list<array{line: int, content: string}> */
    public array $beforeContext;
    /** @var list<array{line: int, content: string}> */
    public array $afterContext;
}

`Greph\Ast\AstMatch`

PHP

final readonly class AstMatch
{
    public string $file;
    public PhpParser\Node $node;
    /** @var array<string, mixed> */
    public array $captures;
    public int $startLine;
    public int $endLine;
    public int $startFilePos;
    public int $endFilePos;
    public string $code;
}

`Greph\Ast\RewriteResult`

PHP

final readonly class RewriteResult
{
    public string $file;
    public string $originalContents;
    public string $rewrittenContents;
    public int $replacementCount;

    public function changed(): bool;
}

`Greph\Index\IndexBuildResult`

PHP

final readonly class IndexBuildResult
{
    public string $rootPath;
    public string $indexPath;
    public int $fileCount;
    public int $trigramCount;
    public int $addedFiles;
    public int $updatedFiles;
    public int $deletedFiles;
    public int $unchangedFiles;
}

AstIndexBuildResult dan AstCacheBuildResult memiliki bentuk yang sama, masing-masing dengan factCount dan cachedTreeCount sebagai pengganti.

Exception

Greph melempar tiga exception bertipe, semuanya di Greph\Exceptions:

Exception	Saat terjadi
`WalkerException`	Kesalahan sistem file saat penelusuran (jalur tidak ditemukan, direktori tidak dapat dibaca)
`PatternException`	Regex atau pola AST tidak valid
`ParseException`	Sumber PHP tidak dapat diparse (hanya saat `skipParseErrors: false`)

Metode pencarian terindeks memunculkan \RuntimeException jika tidak ada indeks di lokasi yang diminta. greph-index CLI menyediakan opsi --fallback scan yang menangkap exception ini lalu beralih ke pemindaian tanpa indeks.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Pencarian teks terindeks

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Pencarian AST terindeks

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter