PHP API

Vaata Markdownina Muuda teenuses GitHub Dokumentatsioon: d105217

`Greph\Greph`

Klass Greph\Greph on staatiline sisenemispunkt. See pakub kõiki otsingu-, ümberkirjutus- ja indekseerimistoiminguid. Kõik meetodid aktsepteerivad kas ühte teed või teede loendit.

PHP

use Greph\Greph;

`walk`

PHP

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

Lahendab $paths tasaseks absoluutsete failiteede FileList-ks. Järgib gitignore'i ja .grephignore reegleid ning failitüübi filtreid, glob-mustreid, peidetud failide kaasamist, sümbollinkide järgimist, binaarfailide tuvastamist ja faili suuruse ülempiiri.

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

Käivitab tekstiotsingu ja tagastab list<TextFileResult>. Iga TextFileResult sisaldab failiteed ja objektide TextMatch loendit (rida, veerg, sisu, tabamused, valikuline 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";
    }
}

Kui jobs > 1 ja failide arv ületab tööprotsesside läve, suunab searchText skannimise automaatselt WorkerPool-le. Vastasel juhul käivitub see protsessisiseselt.

`searchAst`

PHP

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

Käivitab struktuurse AST-otsingu ja tagastab list<AstMatch>. Mustrid kirjutatakse lähtekoodina PHP, kasutades metavariabeleid $VAR ja $$$VARIADIC. Iga AstMatch sisaldab faili, tabatud PhpParser\Node, tabamusi, algus- ja lõpurida, baidiofsette ning sobitatud lähtekoodilõiku.

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

Käivitab struktuurse ümberkirjutuse ja tagastab list<RewriteResult>. Iga RewriteResult sisaldab failiteed, algset sisu, ümberkirjutatud sisu ja asenduste arvu. Vorming säilib: asendatakse ainult sobitatud sõlmede vahemikud, ülejäänud fail jääb puutumata.

PHP

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

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

Fassaad ei kirjuta kettale; helistaja otsustab, kas muudatused rakendada. CLI rakendab need, kui pole määratud --dry-run ega --interactive.

Indekseeritud tekstiotsing

`buildTextIndex`

PHP

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

Koostab värske trigrammi- ja tunnuseesinemiste indeksi asukohale $rootPath. Indeks salvestatakse asukohta $indexPath (vaikimisi $rootPath/.greph-index). $lifecycle võib olla static, manual-refresh, opportunistic-refresh või strict-stale-check. Tagastab objekti IndexBuildResult koos failide ja trigrammide arvuga ning lisatud, uuendatud, kustutatud ja muutmata kirjete arvuga.

`refreshTextIndex`

PHP

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

Värskendab tekstiindeksit järk-järgult. Failide räsi arvutatakse uuesti ja ümber kirjutatakse ainult muudetud kirjed.

`searchTextIndexed`

PHP

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

Käivitab tekstiotsingu soojendatud indeksis. Kui indeksit pole, tagastab käitusaegse vea (kutsuge esmalt buildTextIndex). Tagastab searchText-ga täpselt sama struktuuriga list<TextFileResult>.

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

Käivitab soojendatud tekstiotsingu mitmes tekstiindeksi kataloogis. Greph otsib igast sobivast indeksist, eemaldab absoluutsete failiteede järgi duplikaadid ja kasutab algset skannimist ainult nende teede puhul, mis ei asu ühegi antud indeksi juurkataloogis.

`loadIndexSet`

PHP

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

Laadib indeksikomplekti manifesti, vaikimisi praeguses töökataloogis asuvast failist .greph-index-set.json.

`searchTextIndexedSet`

PHP

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

Lahendab indeksikomplekti manifestist valitud kirjed text ja käivitab toimingu searchTextIndexedMany vaste.

Indekseeritud AST-otsing

`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

Koostab AST-faktide indeksi või värskendab seda järk-järgult. Ekstraheeritud faktid salvestatakse vaikimisi asukohta $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

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

Kasutab faktide indeksit kandidaatide valiku kitsendamiseks ja kontrollib seejärel vasted lähtekoodi põhjal uuesti üle. Tagastab searchAst-ga sama struktuuriga list<AstMatch>.

`searchAstIndexedMany`

PHP

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

Käivitab soojendatud AST-faktiotsingu mitmes AST-indeksi kataloogis.

`searchAstIndexedSet`

PHP

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

Lahendab indeksikomplekti manifestist valitud kirjed ast-index ja käivitab toimingu searchAstIndexedMany vaste.

`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

Koostab vahemällu salvestatud parsitud puude hoidla või värskendab seda järk-järgult. Serialiseeritud puud salvestatakse vaikimisi asukohta $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

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

Käivitab AST-otsingu vahemällu salvestatud parsitud puudel ja jätab parseri täielikult vahele. Tagastab searchAst-ga sama struktuuriga list<AstMatch>.

`searchAstCachedMany`

PHP

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

Käivitab soojendatud vahemällu salvestatud AST-otsingu mitmes vahemälukataloogis.

`searchAstCachedSet`

PHP

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

Lahendab indeksikomplekti manifestist valitud kirjed ast-cache ja käivitab toimingu searchAstCachedMany vaste.

`Greph\Text\TextSearchOptions`

Ainult lugemiseks mõeldud tekstiotsingu valikute objekt.

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

Valideerimine:

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

Kasutage walkOptions(), et tuletada vastav WalkOptions, kui soovite failipuus eraldi liikuda.

tracePlan kasutavad soojendatud indeksiotsijad ning greph-index CLI edastavad plaanuri diagnostika stderr-le. Algne searchText seda ise ei kasuta.

`Greph\Ast\AstSearchOptions`

Ainult lugemiseks mõeldud AST-otsingu ja ümberkirjutuse valikute objekt.

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-režiimi vaikefailitüübi filter on php. Kui skipParseErrors väärtus on true (vaikimisi), jäetakse parsimisel nurjunud failid vaikselt vahele; määrake selle väärtuseks false, et kuvada parsimisvead eranditena. tracePlan kasutavad soojendatud AST-otsijad ja greph-index ast-index|ast-cache search kasutab seda kandidaatide kõrvaldamise diagnostika kuvamiseks.

`Greph\Walker\WalkOptions`

Ainult lugemiseks mõeldud failipuus liikumise valikute objekt.

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`

Lahendab nimetatud failitüübid laiendite loenditeks. Sisseehitatud aliased:

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

Tulemiobjektid

`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 ja AstCacheBuildResult järgivad sama kuju, kus vastavalt asendatakse factCount ja cachedTreeCount.

Erandid

Greph viskab kolm tüübistatud erandit, kõik Greph\Exceptions-s:

Erand	Millal see tekib
`WalkerException`	Failisüsteemi vead läbimisel (puuduv tee, loetamatu kataloog)
`PatternException`	Vigane regex või AST muster
`ParseException`	PHP lähtekoodi ei saanud parsida (ainult kui `skipParseErrors: false`)

Indekseeritud otsingumeetodid viskavad erandi \RuntimeException, kui küsitud asukohas indeksit pole. greph-index CLI pakub suvandit --fallback scan, mis püüab need erandid kinni ja kasutab selle asemel indekseerimata skannimist.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Indekseeritud tekstiotsing

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Indekseeritud AST-otsing

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter