PHP API

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: d105217

`Greph\Greph`

Klasa Greph\Greph jest statycznym punktem wejścia. Udostępnia wszystkie operacje wyszukiwania, przepisywania i indeksowania. Wszystkie metody przyjmują pojedynczą ścieżkę lub listę ścieżek.

PHP

use Greph\Greph;

`walk`

PHP

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

Rozwiązuje $paths do płaskiej listy FileList bezwzględnych ścieżek plików. Uwzględnia gitignore, .grephignore, filtry typów plików, wzorce glob, uwzględnianie ukrytych plików, podążanie za dowiązaniami symbolicznymi, wykrywanie plików binarnych oraz limit maksymalnego rozmiaru pliku.

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

Wykonuje wyszukiwanie tekstowe i zwraca list<TextFileResult>. Każdy TextFileResult udostępnia ścieżkę pliku oraz listę obiektów TextMatch (wiersz, kolumna, treść, przechwycone wartości, opcjonalny kontekst).

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

Gdy jobs > 1, a liczba plików przekracza próg dla procesów roboczych, searchText automatycznie przekazuje skanowanie do WorkerPool. W przeciwnym razie działa w bieżącym procesie.

`searchAst`

PHP

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

Wykonuje strukturalne wyszukiwanie AST i zwraca list<AstMatch>. Wzorce zapisuje się jako kod źródłowy PHP z metavariables $VAR i $$$VARIADIC. Każdy AstMatch zawiera plik, przechwycone PhpParser\Node, przechwycone wartości, numery wierszy i przesunięcia bajtowe początku oraz końca, a także dopasowany fragment kodu źródłowego.

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

Wykonuje strukturalne przepisywanie i zwraca list<RewriteResult>. Każdy RewriteResult udostępnia ścieżkę pliku, oryginalną treść, zmienioną treść i liczbę zamian. Przepisywanie zachowuje format: podmieniane są tylko zakresy dopasowanych węzłów, a reszta pliku pozostaje bez zmian.

PHP

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

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

Fasada nie zapisuje zmian na dysku; decyzja o ich zastosowaniu należy do wywołującego. CLI stosuje je, chyba że ustawiono --dry-run lub --interactive.

Indeksowane wyszukiwanie tekstu

`buildTextIndex`

PHP

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

Tworzy nowy indeks trygramów i pozycji identyfikatorów dla $rootPath. Indeks jest przechowywany w $indexPath (domyślnie w $rootPath/.greph-index). $lifecycle może mieć wartość static, manual-refresh, opportunistic-refresh lub strict-stale-check. Zwraca IndexBuildResult zawierający liczbę plików i trygramów oraz liczby dodanych, zaktualizowanych, usuniętych i niezmienionych elementów.

`refreshTextIndex`

PHP

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

Przyrostowo odświeża istniejący indeks tekstowy. Pliki są ponownie haszowane, a przepisywane są tylko zmienione wpisy.

`searchTextIndexed`

PHP

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

Wykonuje wyszukiwanie tekstu w rozgrzanym indeksie. Jeśli indeks nie istnieje, zwraca błąd środowiska uruchomieniowego (najpierw wywołaj buildTextIndex). Zwraca list<TextFileResult> o strukturze identycznej z 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

Wykonuje wyszukiwanie tekstu w rozgrzanych indeksach w kilku katalogach. Greph przeszukuje każdy właściwy indeks, usuwa duplikaty na podstawie bezwzględnej ścieżki pliku i uruchamia natywne skanowanie tylko dla ścieżek spoza wszystkich podanych katalogów głównych indeksów.

`loadIndexSet`

PHP

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

Wczytuje manifest zestawu indeksów, domyślnie .greph-index-set.json w bieżącym katalogu roboczym.

`searchTextIndexedSet`

PHP

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

Rozwiązuje wybrane wpisy text z manifestu zestawu indeksów i uruchamia odpowiednik searchTextIndexedMany.

Indeksowane wyszukiwanie AST

`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

Tworzy indeks faktów AST lub odświeża go przyrostowo. Domyślnie przechowuje wyodrębnione fakty w $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

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

Używa indeksu faktów, aby zawęzić zbiór kandydatów przed ponownym sprawdzeniem dopasowań w kodzie źródłowym. Zwraca wynik o takiej samej strukturze list<AstMatch> jak searchAst.

`searchAstIndexedMany`

PHP

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

Wykonuje wyszukiwanie faktów AST w rozgrzanych indeksach w kilku katalogach.

`searchAstIndexedSet`

PHP

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

Rozwiązuje wybrane wpisy ast-index z manifestu zestawu indeksów i uruchamia odpowiednik 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

Tworzy magazyn sparsowanych drzew w pamięci podręcznej lub odświeża go przyrostowo. Domyślnie przechowuje serializowane drzewa w $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

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

Wykonuje wyszukiwanie AST w sparsowanych drzewach z pamięci podręcznej, całkowicie pomijając parser. Zwraca wynik o takiej samej strukturze list<AstMatch> jak searchAst.

`searchAstCachedMany`

PHP

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

Wykonuje wyszukiwanie w rozgrzanej pamięci podręcznej AST w kilku katalogach pamięci podręcznej.

`searchAstCachedSet`

PHP

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

Rozwiązuje wybrane wpisy ast-cache z manifestu zestawu indeksów i uruchamia odpowiednik searchAstCachedMany.

`Greph\Text\TextSearchOptions`

Niezmienny obiekt opcji wyszukiwania tekstu.

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

Walidacja:

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

Użyj walkOptions(), aby wyznaczyć pasujące WalkOptions, jeśli chcesz osobno przejść po drzewie plików.

tracePlan jest używany przez moduły wyszukiwania w rozgrzanym indeksie, a greph-index CLI służą do przekazywania diagnostyki planera do stderr. Natywny searchText sam z niego nie korzysta.

`Greph\Ast\AstSearchOptions`

Niezmienny obiekt opcji wyszukiwania i przepisywania 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,
)

Domyślny filtr typów plików w trybie AST to php. Gdy skipParseErrors ma wartość true (domyślną), pliki, których nie można sparsować, są po cichu pomijane; ustaw tę opcję na false, aby błędy parsowania były zgłaszane jako wyjątki. tracePlan jest używane przez rozgrzane wyszukiwarki AST, a greph-index ast-index|ast-cache search służy do emitowania diagnostyki przycinania kandydatów.

`Greph\Walker\WalkOptions`

Obiekt opcji tylko do odczytu dla przechodzenia po plikach.

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`

Rozwiązuje nazwane typy plików do list rozszerzeń. Wbudowane aliasy:

Alias	Rozszerzenia
`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']);

Obiekty wynikowe

`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 i AstCacheBuildResult mają tę samą strukturę, z odpowiednio podstawionymi factCount i cachedTreeCount.

Wyjątki

Greph zgłasza trzy typowane wyjątki, wszystkie z Greph\Exceptions:

Wyjątek	Kiedy jest zgłaszany
`WalkerException`	Błędy systemu plików podczas przechodzenia (brakująca ścieżka, katalog bez dostępu do odczytu)
`PatternException`	Nieprawidłowe wyrażenie regularne lub wzorzec AST
`ParseException`	Nie można sparsować źródła PHP (tylko gdy `skipParseErrors: false`)

Metody wyszukiwania indeksowanego zgłaszają \RuntimeException, gdy w żądanej lokalizacji nie ma indeksu. greph-index CLI udostępnia opcję --fallback scan, która przechwytuje te błędy i zamiast tego przeprowadza skanowanie bez indeksu.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Indeksowane wyszukiwanie tekstu

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Indeksowane wyszukiwanie AST

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter