PHP API

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: d105217

`Greph\Greph`

Greph\Greph klasė yra statinis įvesties taškas. Ji suteikia visas paieškos, perrašymo ir indeksavimo operacijas. Kiekvienas metodas priima vieną kelią arba kelių sąrašą.

PHP

use Greph\Greph;

`walk`

PHP

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

Paverčia $paths į plokščią absoliučių failų kelių FileList. Atsižvelgiama į gitignore, .grephignore, failų tipų filtrus, glob šablonus, paslėptų failų įtraukimą, simbolinių nuorodų sekimą, dvejetainių failų aptikimą ir didžiausio failo dydžio ribą.

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

Atlieka teksto paiešką ir pateikia list<TextFileResult>. Kiekviename TextFileResult yra failo kelias ir TextMatch objektų sąrašas (eilutė, stulpelis, turinys, užfiksuotos reikšmės, pasirinktinis kontekstas).

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

Kai nustatyta jobs > 1 ir failų skaičius viršija darbininkų ribą, searchText automatiškai perduoda peržiūrą WorkerPool. Kitu atveju ji vykdoma tame pačiame procese.

`searchAst`

PHP

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

Atlieka struktūrinę AST paiešką ir pateikia list<AstMatch>. Šablonai rašomi kaip PHP kodas su $VAR ir $$$VARIADIC metakintamaisiais. Kiekviename AstMatch yra failas, užfiksuotas PhpParser\Node, užfiksuotos reikšmės, pradžios ir pabaigos eilučių bei baitų poslinkiai ir atitinkantis pirminio kodo fragmentas.

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

Atlieka struktūrinį perrašymą ir pateikia list<RewriteResult>. Kiekviename RewriteResult yra failo kelias, pradinis turinys, perrašytas turinys ir pakeitimų skaičius. Perrašymai išsaugo formatą: pakeičiami tik atitinkančių mazgų fragmentai, o likusi failo dalis paliekama nepakeista.

PHP

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

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

Fasadas į diską nerašo; skambinantysis nusprendžia, ar pritaikyti pakeitimus. CLI juos pritaiko, nebent nustatyta --dry-run arba --interactive.

Indeksuota teksto paieška

`buildTextIndex`

PHP

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

Sukuria naują trigramų ir identifikatorių įrašų indeksą, skirtą $rootPath. Indeksas saugomas $indexPath (numatytoji vieta – $rootPath/.greph-index). $lifecycle gali būti static, manual-refresh, opportunistic-refresh arba strict-stale-check. Pateikia IndexBuildResult, kuriame nurodytas failų ir trigramų skaičius, taip pat pridėtų, atnaujintų, pašalintų ir nepakeistų įrašų skaičius.

`refreshTextIndex`

PHP

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

Palaipsniui atnaujina esamą teksto indeksą. Failų maišos reikšmės apskaičiuojamos iš naujo, o perrašomi tik pasikeitę įrašai.

`searchTextIndexed`

PHP

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

Atlieka teksto paiešką pagal paruoštą indeksą. Jei indeksas neegzistuoja, pateikiama vykdymo klaida (pirmiausia iškvieskite buildTextIndex). Grąžinama list<TextFileResult>, kurios struktūra visiškai tokia pati kaip 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

Atlieka teksto paiešką pagal paruoštus indeksus keliuose kataloguose. Greph ieško kiekviename taikomame indekse, pašalina dublikatus pagal absoliutų failo kelią, o natūralią peržiūrą vykdo tik tų kelių, kurie nepatenka į nė vieno pateikto indekso šakninį katalogą, atžvilgiu.

`loadIndexSet`

PHP

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

Įkelia indeksų rinkinio aprašą; numatytoji vieta – .greph-index-set.json dabartiniame darbiniame kataloge.

`searchTextIndexedSet`

PHP

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

Iš indeksų rinkinio aprašo parenka text įrašus ir atlieka veiksmą, atitinkantį searchTextIndexedMany.

Indeksuota AST paieška

`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

Sukuria arba palaipsniui atnaujina AST faktų indeksą. Išgauti faktai pagal numatytuosius nustatymus saugomi $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

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

Naudoja faktų indeksą galimų atitikmenų skaičiui sumažinti, o tada šaltinyje pakartotinai patikrina atitikmenis. Pateikia tokios pačios struktūros list<AstMatch> kaip searchAst.

`searchAstIndexedMany`

PHP

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

Atlieka AST faktų paiešką pagal paruoštus indeksus keliuose AST indeksų kataloguose.

`searchAstIndexedSet`

PHP

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

Iš indeksų rinkinio aprašo parenka ast-index įrašus ir atlieka veiksmą, atitinkantį 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

Sukuria arba palaipsniui atnaujina podėlyje saugomą išanalizuotų medžių saugyklą. Serijiniu būdu pateikti medžiai pagal numatytuosius nustatymus saugomi $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

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

Atlieka AST paiešką podėlyje saugomuose išanalizuotuose medžiuose, visiškai praleisdama analizatorių. Pateikia tokios pačios struktūros list<AstMatch> kaip searchAst.

`searchAstCachedMany`

PHP

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

Atlieka AST paiešką pagal paruoštą podėlį keliuose podėlio kataloguose.

`searchAstCachedSet`

PHP

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

Iš indeksų rinkinio aprašo parenka ast-cache įrašus ir atlieka veiksmą, atitinkantį searchAstCachedMany.

`Greph\Text\TextSearchOptions`

Tik skaitymui skirtas teksto paieškos parinkčių objektas.

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

Tikrinimas:

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

Jei norite atskirai pereiti failų medį, naudokite walkOptions(), kad nustatytumėte atitinkamą WalkOptions.

tracePlan naudoja paruoštos indeksuotos paieškos priemonės, o greph-index CLI eiga pateikia planavimo diagnostiką į stderr. Natūrali searchText pati jos nenaudoja.

`Greph\Ast\AstSearchOptions`

Tik skaitymui skirtas AST paieškos ir perrašymo parinkčių objektas.

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

Numatytasis AST režimo failų tipų filtras yra php. Kai skipParseErrors nustatyta į true (numatytoji reikšmė), nepavykusių išanalizuoti failų tyliai atsisakoma; nustatykite false, kad analizės klaidos būtų pateikiamos kaip išimtys. tracePlan naudoja paruoštos AST paieškos priemonės, o greph-index ast-index|ast-cache search – galimų atitikmenų mažinimo diagnostikai pateikti.

`Greph\Walker\WalkOptions`

Tik skaitymui skirtas failų peržiūros priemonės parinkčių objektas.

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`

Paverčia pavadintus failų tipus plėtinių sąrašais. Įtaisytieji slapyvardžiai:

Slapyvardis	Plėtiniai
`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']);

Rezultatų objektai

`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 ir AstCacheBuildResult turi tokią pačią formą, atitinkamai pakeitus factCount ir cachedTreeCount.

Išimtys

Greph išmeta tris tipizuotas išimtis, visas iš Greph\Exceptions:

Išimtis	Kada išmetama
`WalkerException`	Failų sistemos klaidos naršant (trūkstamas kelias, neįskaitomas katalogas)
`PatternException`	Netaisyklinga regex išraiška arba AST šablonas
`ParseException`	Nepavyko išanalizuoti PHP šaltinio (tik kai `skipParseErrors: false`)

Indeksuotos paieškos metodai išmeta \RuntimeException, kai prašomoje vietoje nėra indekso. greph-index CLI pateikia parinktį --fallback scan, kuri šias klaidas perima ir vietoj to atlieka neindeksuotą paiešką.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Indeksuota teksto paieška

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Indeksuota AST paieška

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter