PHP API

Vizualizați ca Markdown Editați pe GitHub Documentație la d105217

`Greph\Greph`

Clasa Greph\Greph este punctul de intrare static. Expune toate operațiile de căutare, rescriere și indexare. Toate metodele acceptă fie o singură cale, fie o listă de căi.

PHP

use Greph\Greph;

`walk`

PHP

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

Rezolvați $paths într-o listă liniară FileList de căi absolute ale fișierelor. Respectă gitignore, .grephignore, filtrele de tipuri de fișiere, tiparele glob, includerea fișierelor ascunse, urmărirea legăturilor simbolice, detectarea fișierelor binare și limita maximă pentru dimensiunea fișierelor.

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

Rulați o căutare text și returnați un list<TextFileResult>. Fiecare TextFileResult expune calea fișierului și o listă de obiecte TextMatch (linie, coloană, conținut, capturi, context opțional).

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

Când jobs > 1 și numărul de fișiere depășește pragul pentru workeri, searchText distribuie automat scanarea către un WorkerPool. În caz contrar, rulează în proces.

`searchAst`

PHP

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

Rulați o căutare structurală AST și returnați un list<AstMatch>. Tiparele sunt scrise ca sursă PHP, cu metacaracterele $VAR și $$$VARIADIC. Fiecare AstMatch include fișierul, elementul PhpParser\Node capturat, capturile, liniile de început și sfârșit, decalajele în octeți și fragmentul sursă găsit.

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

Rulați o rescriere structurală și returnați un list<RewriteResult>. Fiecare RewriteResult expune calea fișierului, conținutul original, conținutul rescris și numărul de înlocuiri. Rescrierile păstrează formatarea: sunt înlocuite doar intervalele nodurilor găsite; restul fișierului rămâne neatins.

PHP

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

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

Fațada nu scrie pe disc; apelantul decide dacă aplică modificările. CLI le aplică, cu excepția cazului în care este setat --dry-run sau --interactive.

Căutare în text indexat

`buildTextIndex`

PHP

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

Construiți un index nou cu liste de apariții pentru trigrame și identificatori pentru $rootPath. Indexul este stocat în $indexPath (implicit la $rootPath/.greph-index). $lifecycle poate fi static, manual-refresh, opportunistic-refresh sau strict-stale-check. Returnează un IndexBuildResult cu numărul de fișiere, numărul de trigrame și numărul de elemente adăugate, actualizate, șterse sau neschimbate.

`refreshTextIndex`

PHP

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

Actualizați incremental un index de text existent. Fișierele sunt re-hash-uite și sunt rescrise doar intrările modificate.

`searchTextIndexed`

PHP

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

Rulați o căutare text în indexul încălzit. Dacă indexul nu există, apare o eroare la runtime (apelați mai întâi buildTextIndex). Returnează un list<TextFileResult> cu aceeași structură ca 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

Rulați o căutare text încălzită în mai multe directoare de indexare a textului. Greph caută în fiecare index aplicabil, elimină duplicatele după calea absolută a fișierului și revine la scanarea nativă doar pentru căile din afara tuturor rădăcinilor de indexare furnizate.

`loadIndexSet`

PHP

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

Încărcați un manifest de set de indexuri, implicit .greph-index-set.json din directorul de lucru curent.

`searchTextIndexedSet`

PHP

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

Rezolvați intrările text selectate dintr-un manifest de set de indexuri și rulați echivalentul lui searchTextIndexedMany.

Căutare AST indexată

`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

Construiți sau actualizați incremental indexul de fapte AST. Faptele extrase sunt stocate implicit în $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

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

Folosiți indexul de fapte pentru a restrânge candidații înainte de a reverifica potrivirile în sursă. Returnează aceeași structură list<AstMatch> ca searchAst.

`searchAstIndexedMany`

PHP

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

Rulați o căutare AST încălzită în indexul de fapte în mai multe directoare de indexuri AST.

`searchAstIndexedSet`

PHP

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

Rezolvați intrările ast-index selectate dintr-un manifest de set de indexuri și rulați echivalentul lui 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

Construiți sau actualizați incremental depozitul de arbori analizați în cache. Arborii serializați sunt stocați implicit în $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

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

Rulați o căutare AST pe arborii analizați din cache, omițând complet analizatorul. Returnează aceeași structură list<AstMatch> ca searchAst.

`searchAstCachedMany`

PHP

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

Rulați o căutare AST încălzită în cache în mai multe directoare de cache.

`searchAstCachedSet`

PHP

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

Rezolvați intrările ast-cache selectate dintr-un manifest de set de indexuri și rulați echivalentul lui searchAstCachedMany.

`Greph\Text\TextSearchOptions`

Obiect readonly cu opțiuni pentru căutarea textului.

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

Validare:

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

Folosiți walkOptions() pentru a obține WalkOptions corespunzător dacă doriți să parcurgeți separat arborele de fișiere.

tracePlan este folosit de motoarele de căutare cu index încălzit, iar fluxurile greph-index CLI pentru a emite diagnosticări ale planificatorului către stderr. searchText nativ nu îl folosește.

`Greph\Ast\AstSearchOptions`

Obiect readonly cu opțiuni pentru căutarea și rescrierea 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,
)

Filtrul implicit pentru tipul de fișier în modul AST este php. Când skipParseErrors este true (implicit), fișierele care nu pot fi analizate sunt omise fără mesaj; activați false pentru a afișa erorile de analiză ca excepții. tracePlan este folosit de căutările AST încălzite, iar greph-index ast-index|ast-cache search pentru a emite diagnostice de eliminare a candidaților.

`Greph\Walker\WalkOptions`

Obiect cu opțiuni doar pentru citire pentru parcurgătorul de fișiere.

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`

Rezolvă tipurile de fișiere denumite la liste de extensii. Aliasuri încorporate:

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

Obiecte rezultat

`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 au aceeași structură, cu factCount și, respectiv, cachedTreeCount înlocuite.

Excepții

Greph aruncă trei excepții tipizate, toate în Greph\Exceptions:

Excepție	Când este declanșată
`WalkerException`	Erori de sistem de fișiere în timpul parcurgerii (cale lipsă, director inaccesibil)
`PatternException`	Expresie regulată sau model AST nevalid
`ParseException`	Sursa PHP nu a putut fi analizată (doar când `skipParseErrors: false`)

Metodele de căutare indexată aruncă \RuntimeException când nu există niciun index în locația solicitată. greph-index CLI expune o opțiune --fallback scan care detectează aceste excepții și revine la o scanare fără index.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Căutare în text indexat

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Căutare AST indexată

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter