PHP API

Bekijken als Markdown Bewerken op GitHub Documentatie op d105217

`Greph\Greph`

De klasse Greph\Greph is het statische toegangspunt. Deze biedt elke zoek-, herschrijf- en indexbewerking. Alle methoden accepteren één pad of een lijst met paden.

PHP

use Greph\Greph;

`walk`

PHP

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

Los $paths op naar een platte FileList met absolute bestandspaden. Houdt rekening met gitignore, .grephignore, bestandstypefilters, globpatronen, het opnemen van verborgen bestanden, het volgen van symlinks, binaire detectie en de maximale bestandsgroottelimiet.

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

Voer een tekstzoekopdracht uit en geef een list<TextFileResult> terug. Elk TextFileResult bevat het bestandspad en een lijst met TextMatch-objecten (regel, kolom, inhoud, captures, optionele context).

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

Wanneer jobs > 1 is ingeschakeld en het aantal bestanden de workergrens overschrijdt, stuurt searchText de scan automatisch naar een WorkerPool. Anders wordt deze binnen hetzelfde proces uitgevoerd.

`searchAst`

PHP

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

Voer een structurele AST-zoekopdracht uit en geef een list<AstMatch> terug. Patronen worden geschreven als broncode in PHP, met metavariabelen $VAR en $$$VARIADIC. Elke AstMatch bevat het bestand, de vastgelegde PhpParser\Node, de captures, de begin- en eindregel en byte-offsets, en het overeenkomende bronfragment.

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

Voer een structurele herschrijving uit en geef een list<RewriteResult> terug. Elk RewriteResult bevat het bestandspad, de oorspronkelijke inhoud, de herschreven inhoud en het aantal vervangingen. Bij herschrijvingen blijft de opmaak behouden: alleen de bereiken van overeenkomende knooppunten worden vervangen; de rest van het bestand blijft onaangeroerd.

PHP

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

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

De facade schrijft niet naar schijf; de aanroeper bepaalt of de wijzigingen worden toegepast. CLI voert ze uit, tenzij --dry-run of --interactive is ingesteld.

Geïndexeerd tekstzoeken

`buildTextIndex`

PHP

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

Bouw een nieuwe trigram- en identifier-postingsindex voor $rootPath. De index wordt opgeslagen in $indexPath (standaard $rootPath/.greph-index). $lifecycle kan static, manual-refresh, opportunistic-refresh of strict-stale-check zijn. Geeft een IndexBuildResult terug met het aantal bestanden, het aantal trigrams en de aantallen toegevoegde, bijgewerkte, verwijderde en ongewijzigde bestanden.

`refreshTextIndex`

PHP

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

Vernieuw een bestaande tekstindex incrementeel. Bestanden worden opnieuw gehasht en alleen gewijzigde vermeldingen worden herschreven.

`searchTextIndexed`

PHP

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

Voer een tekstzoekopdracht uit op de opgewarmde index. Geeft een runtimefout als de index niet bestaat (roep eerst buildTextIndex aan). Geeft een list<TextFileResult> terug met precies dezelfde structuur als 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

Voer een tekstzoekopdracht uit op opgewarmde tekstindexen in meerdere directories. Greph doorzoekt elke toepasselijke index, verwijdert duplicaten op basis van het absolute bestandspad en voert alleen een native scan uit voor paden buiten alle opgegeven indexroots.

`loadIndexSet`

PHP

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

Laad een manifest voor een indexset, standaard .greph-index-set.json in de huidige werkdirectory.

`searchTextIndexedSet`

PHP

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

Los de geselecteerde vermeldingen van text op vanuit een manifest voor een indexset en voer het equivalent van searchTextIndexedMany uit.

Geïndexeerd AST-zoeken

`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

Bouw de feitenindex voor AST's of vernieuw deze incrementeel. Opgeslagen feiten staan standaard in $rootPath/.greph-ast-index.

`searchAstIndexed`

PHP

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

Gebruik de feitenindex om kandidaten te beperken voordat overeenkomsten opnieuw worden gecontroleerd aan de hand van de broncode. Geeft dezelfde list<AstMatch>-structuur terug als searchAst.

`searchAstIndexedMany`

PHP

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

Voer een AST-feitenzoekopdracht uit op opgewarmde indexen in meerdere AST-indexdirectories.

`searchAstIndexedSet`

PHP

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

Los de geselecteerde vermeldingen van ast-index op vanuit een manifest voor een indexset en voer het equivalent van searchAstIndexedMany uit.

`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

Bouw de cache voor geparste bomen of vernieuw deze incrementeel. Geserialiseerde bomen worden standaard opgeslagen in $rootPath/.greph-ast-cache.

`searchAstCached`

PHP

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

Zoek in de gecachte geparste bomen naar AST's en sla de parser volledig over. Geeft dezelfde list<AstMatch>-structuur terug als searchAst.

`searchAstCachedMany`

PHP

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

Voer een zoekopdracht uit op de opgewarmde gecachte AST's in meerdere cachdirectories.

`searchAstCachedSet`

PHP

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

Los de geselecteerde vermeldingen van ast-cache op vanuit een manifest voor een indexset en voer het equivalent van searchAstCachedMany uit.

`Greph\Text\TextSearchOptions`

Alleen-lezenoptiesobject voor tekstzoeken.

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

Validatie:

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

Gebruik walkOptions() om de bijbehorende WalkOptions af te leiden als u de bestandsstructuur afzonderlijk wilt doorlopen.

tracePlan wordt gebruikt door opgewarmde geïndexeerde zoekers en greph-index CLI-stromen om plannerdiagnostiek naar stderr uit te voeren. Native searchText gebruikt dit zelf niet.

`Greph\Ast\AstSearchOptions`

Alleen-lezenoptiesobject voor AST-zoeken en herschrijven.

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

Het standaardfilter voor bestandstypen in de AST-modus is php. Als skipParseErrors true is (standaard), worden bestanden die niet kunnen worden geparst stilzwijgend overgeslagen; stel deze in op false om parsefouten als uitzonderingen weer te geven. tracePlan wordt gebruikt door opgewarmde AST-zoekers en greph-index ast-index|ast-cache search om diagnostiek over het beperken van kandidaten uit te voeren.

`Greph\Walker\WalkOptions`

Alleen-lezenoptiesobject voor de bestandswalker.

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`

Zet benoemde bestandstypen om in extensielijsten. Ingebouwde aliassen:

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

Resultaatobjecten

`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 en AstCacheBuildResult volgen dezelfde vorm, waarbij respectievelijk factCount en cachedTreeCount zijn ingevuld.

Uitzonderingen

Greph werpt drie getypeerde uitzonderingen op, allemaal in Greph\Exceptions:

Uitzondering	Wanneer deze wordt opgeworpen
`WalkerException`	Bestandssysteemfouten tijdens het doorlopen (ontbrekend pad, onleesbare map)
`PatternException`	Ongeldige regex of AST-patroon
`ParseException`	De PHP-bron kon niet worden geparseerd (alleen wanneer `skipParseErrors: false`)

Geïndexeerde zoekmethoden werpen \RuntimeException op wanneer er op de gevraagde locatie geen index aanwezig is. De greph-index CLI biedt een optie --fallback scan die deze fouten opvangt en in plaats daarvan terugvalt op een scan zonder index.

PHP API

Greph\Greph

walk

searchText

searchAst

rewriteAst

Geïndexeerd tekstzoeken

buildTextIndex

refreshTextIndex

searchTextIndexed

searchTextIndexedMany

loadIndexSet

searchTextIndexedSet

Geïndexeerd AST-zoeken

buildAstIndex / refreshAstIndex

searchAstIndexed

searchAstIndexedMany

searchAstIndexedSet

buildAstCache / refreshAstCache

searchAstCached

searchAstCachedMany

searchAstCachedSet

Greph\Text\TextSearchOptions

Greph\Ast\AstSearchOptions

Greph\Walker\WalkOptions

Greph\Walker\FileTypeFilter