Kom godt i gang

Installation

Installer Greph via Composer:

composer require greph/greph

Dette installerer biblioteket og fire eksekverbare filer i vendor/bin/:

• greph: native tekstsøgninger, AST-søgninger og AST-omskrivninger
• greph-index: opvarmet tekstindeks, AST-faktaindeks og cachelagret AST-søgning
• rg: kompatibilitetswrapper i stil med ripgrep
• sg: kompatibilitetswrapper i stil med ast-grep

Disse eksekverbare filer fungerer fra vendor/bin/ i dit projekt, da Greph 0.2.3. Ældre udgivelser fandt kun Composer-autoloaderen i en klon af repositoriet Greph, så brug mindst denne version:

composer require greph/greph:^0.2.3

Krav

• PHP 8.2+ til readonly-klasser, enums, førsteklasses callable-syntaks og constructor promotion
• ext-json til JSON-output og payloads til indekset på disken
• ext-ctype til mønster- og indstillingsparsing
• ext-tokenizer til PHP-Parser og AST-prefiltrene
• ext-zlib til det cachelagrede AST-lager (greph-index ast-cache)
• nikic/php-parser (installeres automatisk som en Composer-afhængighed)

ext-json, ext-ctype og ext-tokenizer er aktiveret i næsten alle PHP-builds. composer.json erklærer i øjeblikket kun ext-json (#5), så Composer advarer ikke, hvis en af de andre mangler.

Valgfrit:

• ext-pcntl til parallelle scanninger. Greph går problemfrit over til kørsel i én proces, hvis det mangler.
• Eksterne binærfiler til rg, grep og sg til benchmark-sammenligninger. De er aldrig nødvendige ved kørsel.

Søgning, omskrivning og indeksering kalder aldrig proc_open() eller shell_exec(); kun parallelle scanninger forgrener processer, og de falder tilbage til én proces uden pcntl_fork(). Se Procesbegrænsede værter for værter, der deaktiverer proc_open(), shell_exec() eller pcntl_fork().

Din første tekstsøgning

Grephs standardtilstand er grep-kompatibel tekstsøgning:

vendor/bin/greph -F "function" src

Outputtet bruger det kanoniske file:line:content-format, som grep, ripgrep og de fleste editorintegrationer forventer.

src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(

Tilføj -i for søgning uden forskel på store og små bogstaver, -w for hele ord, -c for antal, -l for kun filstier, -C 2 for to kontekstlinjer osv. Den fulde liste findes i CLI-referencen.

Din første AST-søgning

Angiv -p og et mønster udformet som PHP for at skifte til strukturel søgning:

vendor/bin/greph -p 'new $CLASS()' src

$CLASS er en metavariabel, der indfanger ethvert klassenavn. Mønsteret new $CLASS() matcher alle new-udtryk uden argumenter, uanset klasse, formatering eller kommentarer. Brug new $CLASS($$$ARGS) til at matche kald med vilkårlige argumenter.

Hvert AST-match udskrives som filen, startlinjen og den matchede kode:

src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()

Andre nyttige mønstre:

# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src

# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src

Se Tilstande / AST-søgning for hele mønstersyntaksen.

Din første omskrivning

Tilføj -r for at omdanne AST-søgningen til en omskrivning:

# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Omskrivninger bevarer formateringen uden for matchet: Kun den matchede node erstattes, mens omgivende mellemrum, indrykning og kommentarer bevares. Selve den matchede node udskrives på ny ud fra skabelonen, så dens layout normaliseres, og en kommentar i den kan gå tabt. Se Tilstande / Omskrivning for detaljer.

PHP API

Den statiske Greph\Greph-facade giver adgang til de samme handlinger som CLI:

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

Den fulde funktionalitet er beskrevet i API.

Indekseret søgning

Gentagne arbejdsbelastninger drager fordel af opvarmede indekser. Byg indekset én gang, og forespørg derefter mange gange:

# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src

Indekserne ligger som standard i .greph-index, .greph-ast-index og .greph-ast-cache i projektets rodmappe.

Vælg en livscyklusprofil til træer, der ændrer sig aktivt, i stedet for at behandle alle opvarmede indekser ens:

vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh

Det almindelige mønster er:

• behold en stabil baseline som static
• behold overlays, der ændrer sig aktivt, som opportunistic-refresh
• undersøg forældet adfærd med stats --dry-refresh

Søgning i flere opvarmede indekser

Du kan søge i flere opvarmede indekser med én kommando:

vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin

Navngivne indekssæt

Hvis du gør det gentagne gange, kan du angive layoutet i .greph-index-set.json og bruge sætunderkommandoerne i stedet for at gentage flagene:

vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Planlæggerens spor

Se, hvordan søgning i opvarmede indekser indsnævrer kandidaterne, ved at tilføje --trace-plan:

vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .

Se Indekseret / Tekst og Indekseret / AST for hele arbejdsgangen med opvarmede indekser.

Kompatibilitetswrappere

Hvis du har værktøjer eller agenter, der allerede bruger ripgrep eller ast-grep, kan du sætte wrapperne ind:

vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Begge wrappere genbruger den samme motor og er verificeret mod de oprindelige binærfiler. Den verificerede funktionalitet er dokumenteret i Kompatibilitet / rg og Kompatibilitet / sg og gengivet i den genererede funktionsmatrix.

Konfiguration

Greph bruger to konventioner for filer på disken:

• .gitignore: følges som standard. Angiv --no-ignore for at slå det fra.
• .grephignore: samme syntaks som .gitignore, anvendt oveni. Nyttigt til værktøjsspecifikke udelukkelser, som du ikke vil have med i versionsstyring.

Standardmapperne til indekser er .greph-index, .greph-ast-index og .greph-ast-cache ved den valgte rod. Tilsidesæt dem med --index-dir på enhver greph-index-underkommando, eller brug .greph-index-set.json til gentagelige layouts med flere indekser.