İçeriğe geç

PHP API

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: d105217

Greph\Greph

Greph\Greph sınıfı statik giriş noktasıdır. Tüm arama, yeniden yazma ve dizin işlemlerini sunar. Tüm yöntemler tek bir yolu veya yol listesini kabul eder.

PHP
use Greph\Greph;

walk

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

$paths değerini mutlak dosya yollarından oluşan düz bir FileList yapısına dönüştürür. gitignore, .grephignore, dosya türü filtreleri, glob desenleri, gizli dosyaları dahil etme, sembolik bağlantıları izleme, ikili dosya algılama ve en büyük dosya boyutu sınırını dikkate alır.

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

Metin araması yapar ve bir list<TextFileResult> döndürür. Her TextFileResult, dosya yolunu ve TextMatch nesnelerinin listesini (satır, sütun, içerik, yakalananlar, isteğe bağlı bağlam) sunar.

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";
    }
}

jobs > 1 etkin olduğunda ve dosya sayısı worker eşiğini aştığında searchText taramayı otomatik olarak bir WorkerPool öğesine yönlendirir. Aksi durumda işlem aynı süreçte çalışır.

searchAst

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

Yapısal AST araması yapar ve bir list<AstMatch> döndürür. Desenler, $VAR ve $$$VARIADIC metavariables içeren PHP kaynak koduyla yazılır. Her AstMatch; dosyayı, yakalanan PhpParser\Node değerini, yakalananları, başlangıç ve bitiş satırları ile bayt ofsetlerini ve eşleşen kaynak dilimini içerir.

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

Yapısal yeniden yazma işlemi yapar ve bir list<RewriteResult> döndürür. Her RewriteResult; dosya yolunu, özgün içeriği, yeniden yazılmış içeriği ve değiştirme sayısını sunar. Yeniden yazma biçimi korur: yalnızca eşleşen düğüm aralıkları değiştirilir; dosyanın geri kalanı olduğu gibi bırakılır.

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

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

Facade diske yazmaz; değişiklikleri uygulayıp uygulamayacağına çağıran taraf karar verir. CLI, --dry-run veya --interactive ayarlanmadığı sürece değişiklikleri uygular.

Dizinlenmiş metin araması

buildTextIndex

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

$rootPath için yeni bir trigram + tanımlayıcı ters dizini oluşturur. Dizin, varsayılan olarak $rootPath/.greph-index konumunda belirlenen $indexPath yolunda saklanır. $lifecycle değeri static, manual-refresh, opportunistic-refresh veya strict-stale-check olabilir. Dosya sayısı, trigram sayısı ve eklenen/güncellenen/silinen/değişmeyen sayılarını içeren bir IndexBuildResult döndürür.

refreshTextIndex

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

Mevcut bir metin dizinini artımlı olarak yeniler. Dosyalar yeniden özetlenir ve yalnızca değişen girdiler yeniden yazılır.

searchTextIndexed

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

Hazır durumdaki dizinde metin araması yapar. Dizin yoksa çalışma zamanı hatası verir (önce buildTextIndex çağırın). searchText ile tam olarak aynı yapıda bir list<TextFileResult> döndürür.

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

Birden fazla metin dizini dizininde hazır durumdaki metin aramasını çalıştırır. Greph, uygulanabilir her dizinde arama yapar, mutlak dosya yoluna göre yinelenen sonuçları tekilleştirir ve yalnızca sağlanan dizin köklerinin dışında kalan yollar için yerel taramaya geri döner.

loadIndexSet

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

Geçerli çalışma dizinindeki varsayılan .greph-index-set.json değerini kullanarak bir dizin kümesi manifestosu yükler.

searchTextIndexedSet

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

Dizin kümesi manifestosundaki seçili text girdilerini çözümler ve searchTextIndexedMany işleminin eşdeğerini çalıştırır.

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

AST olgu dizinini oluşturur veya artımlı olarak yeniler. Çıkarılan olguları varsayılan olarak $rootPath/.greph-ast-index konumunda saklar.

searchAstIndexed

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

Kaynak üzerinde eşleşmeleri yeniden doğrulamadan önce adayları daraltmak için olgu dizinini kullanır. searchAst ile aynı list<AstMatch> yapısını döndürür.

searchAstIndexedMany

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

Birden fazla AST dizin dizininde hazır durumdaki AST olgu aramasını çalıştırır.

searchAstIndexedSet

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

Dizin kümesi manifestosundaki seçili ast-index girdilerini çözümler ve searchAstIndexedMany işleminin eşdeğerini çalıştırır.

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

Önbelleğe alınmış ayrıştırılmış ağaç deposunu oluşturur veya artımlı olarak yeniler. Serileştirilmiş ağaçları varsayılan olarak $rootPath/.greph-ast-cache konumunda saklar.

searchAstCached

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

Ayrıştırıcıyı tamamen atlayarak önbelleğe alınmış ayrıştırılmış ağaçlar üzerinde AST araması yapar. searchAst ile aynı list<AstMatch> yapısını döndürür.

searchAstCachedMany

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

Birden fazla önbellek dizininde hazır durumdaki cached-AST aramasını çalıştırır.

searchAstCachedSet

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

Dizin kümesi manifestosundaki seçili ast-cache girdilerini çözümler ve searchAstCachedMany işleminin eşdeğerini çalıştırır.

Greph\Text\TextSearchOptions

Metin araması için salt okunur seçenekler nesnesi.

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

Doğrulama:

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

Dosya ağacını ayrı olarak taramak istiyorsanız, eşleşen WalkOptions değerini elde etmek için walkOptions() kullanın.

tracePlan, hazır durumdaki dizin arayıcıları tarafından kullanılır; greph-index CLI ise planlayıcı tanılamalarını stderr konumuna iletir. Yerel searchText bunu kullanmaz.

Greph\Ast\AstSearchOptions

AST araması ve yeniden yazma için salt okunur seçenekler nesnesi.

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

AST modu için varsayılan dosya türü filtresi php değeridir. skipParseErrors değeri true olduğunda (varsayılan), ayrıştırılamayan dosyalar sessizce atlanır; ayrıştırma hatalarının istisna olarak bildirilmesi için false olarak değiştirin. tracePlan hazır durumdaki AST arayıcıları tarafından; greph-index ast-index|ast-cache search ise aday eleme tanılamalarını iletmek için kullanılır.

Greph\Walker\WalkOptions

Dosya tarayıcısı için salt okunur seçenekler nesnesi.

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

Adlandırılmış dosya türlerini uzantı listelerine çözümler. Yerleşik takma adlar:

Takma ad Uzantılar
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']);

Sonuç nesneleri

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 ve AstCacheBuildResult aynı yapıyı izler; sırasıyla factCount ve cachedTreeCount kullanılır.

İstisnalar

Greph, tümü Greph\Exceptions içinde bulunan üç türlenmiş istisna fırlatır:

İstisna Oluşma nedeni
WalkerException Tarama sırasında dosya sistemi hataları (yol bulunamadı, dizin okunamıyor)
PatternException Geçersiz regex veya AST deseni
ParseException PHP kaynağı ayrıştırılamadı (yalnızca skipParseErrors: false olduğunda)

Dizinlenmiş arama yöntemleri, istenen konumda dizin bulunmadığında \RuntimeException hatası verir. CLI greph-index, bu hataları yakalayıp dizinsiz taramaya geri dönen bir --fallback scan seçeneği sunar.