Ga naar de inhoud

Aan de slag

Bekijken als Markdown Bewerken op GitHub Documentatie op d105217

Installatie

Installeer Greph via Composer:

Shell
composer require greph/greph

Hiermee worden de bibliotheek en vier uitvoerbare bestanden geïnstalleerd in vendor/bin/:

  • greph: native tekst zoeken, AST zoeken en AST herschrijven
  • greph-index: opgewarmde tekstindex, AST-feitenindex en gecachte AST-zoekopdracht
  • rg: compatibiliteitswrapper in de stijl van ripgrep
  • sg: compatibiliteitswrapper in de stijl van ast-grep

Deze uitvoerbare bestanden werken vanuit de vendor/bin/ van je project, omdat Greph 0.2.3. Eerdere versies vonden de autoloader Composer alleen binnen een kloon van de repository Greph; gebruik daarom ten minste die versie:

Shell
composer require greph/greph:^0.2.3

Vereisten

  • PHP 8.2+ voor readonly-klassen, enums, first-class callable-syntaxis en constructorpromotie
  • ext-json voor JSON-uitvoer en indexpayloads op schijf
  • ext-ctype voor patroon- en optieparsing
  • ext-tokenizer voor PHP-Parser en de AST-prefilters
  • ext-zlib voor de gecachte AST-opslag (greph-index ast-cache)
  • nikic/php-parser (automatisch geïnstalleerd als afhankelijkheid van Composer)

ext-json, ext-ctype en ext-tokenizer zijn in bijna elke PHP-build ingeschakeld. composer.json declareert momenteel alleen ext-json (#5), dus Composer geeft geen waarschuwing als een van de andere ontbreekt.

Optioneel:

  • ext-pcntl voor parallelle scans. Greph schakelt bij ontbreken probleemloos over op uitvoering met één proces.
  • Externe binaire bestanden van rg, grep en sg voor benchmarkvergelijkingen. Ze zijn tijdens runtime nooit vereist.

Zoeken, herschrijven en indexeren roepen nooit proc_open() of shell_exec() aan; alleen parallelle scans forken processen en vallen zonder pcntl_fork() terug op één proces. Zie Hosts met procesbeperkingen voor hosts die proc_open(), shell_exec() of pcntl_fork() uitschakelen.

Je eerste tekstzoekopdracht

De standaardmodus van Greph is tekst zoeken op een manier die compatibel is met grep:

Shell
vendor/bin/greph -F "function" src

De uitvoer gebruikt de canonieke file:line:content-indeling die grep, ripgrep en de meeste editorintegraties verwachten.

Text
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(

Voeg -i toe voor hoofdletterongevoelig zoeken, -w voor hele woorden, -c voor aantallen, -l voor alleen bestandspaden, -C 2 voor twee regels context, enzovoort. De volledige lijst staat in de referentie CLI.

Geef -p en een patroon in de vorm van PHP door om over te schakelen op structureel zoeken:

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

$CLASS is een metavariabele die elke klassenaam vastlegt. Het patroon new $CLASS() komt overeen met elke expressie van new zonder argumenten, ongeacht klasse, opmaak of opmerkingen. Gebruik new $CLASS($$$ARGS) om aanroepen met willekeurige argumenten te vinden.

Elke AST-match wordt weergegeven als bestand, beginregel en overeenkomende code:

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

Andere nuttige patronen:

Shell
# 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

Zie Modi / AST Search voor de volledige patroonsyntaxis.

Je eerste herschrijving

Voeg -r toe om van de AST-zoekopdracht een herschrijving te maken:

Shell
# 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

Bij herschrijvingen blijft de opmaak buiten de match behouden: alleen het overeenkomende knooppunt wordt vervangen en de omliggende witruimte, inspringing en opmerkingen blijven intact. Het knooppunt zelf wordt opnieuw opgemaakt op basis van de sjabloon, waardoor de indeling ervan wordt genormaliseerd en een opmerking erin verloren kan gaan. Zie Modi / Rewrite voor meer informatie.

PHP API

De statische Greph\Greph-facade biedt dezelfde bewerkingen als de CLI:

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

Het volledige aanbod wordt beschreven in API.

Herhaalde taken profiteren van opgewarmde indexen. Bouw de index één keer en voer daarna veel zoekopdrachten uit:

Shell
# 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

Indexen staan standaard in .greph-index, .greph-ast-index en .greph-ast-cache in de projectroot.

Kies voor actief veranderende mappenstructuren een levenscyclusprofiel in plaats van elke opgewarmde index hetzelfde te behandelen:

Shell
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

Het gebruikelijke patroon is:

  • behoud een stabiele basis als static
  • houd actief veranderende overlays bij als opportunistic-refresh
  • inspecteer verouderd gedrag met stats --dry-refresh

Je kunt met één opdracht in meerdere opgewarmde indexen zoeken:

Shell
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

Benoemde indexsets

Als je dit regelmatig doet, zet de indeling dan in .greph-index-set.json en gebruik de set-subopdrachten in plaats van de opties telkens opnieuw op te geven:

Shell
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)' .

Plannertracering

Voeg --trace-plan toe om te zien hoe zoeken met opgewarmde indexen de kandidaten beperkt:

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

Zie Geïndexeerd / Tekst en Geïndexeerd / AST voor de volledige workflow met opgewarmde indexen.

Compatibiliteitswrappers

Als je tools of agents hebt die al met ripgrep of ast-grep werken, kun je de wrappers direct gebruiken:

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

Beide wrappers gebruiken dezelfde engine en zijn met probes gecontroleerd aan de hand van de upstream-binaire bestanden. De gecontroleerde functionaliteit wordt beschreven in Compatibiliteit / rg en Compatibiliteit / sg en is opgenomen in de gegenereerde functiematrix.

Configuratie

Greph herkent twee conventies voor bestanden op schijf:

  • .gitignore: wordt standaard gerespecteerd. Geef --no-ignore door om dit uit te schakelen.
  • .grephignore: dezelfde syntaxis als .gitignore, daar bovenop toegepast. Handig voor tool-specifieke uitsluitingen die je niet in versiebeheer wilt opnemen.

De standaardmappen voor indexen zijn .greph-index, .greph-ast-index en .greph-ast-cache in de gekozen root. Stel een andere map in met --index-dir bij elke greph-index-subopdracht, of gebruik .greph-index-set.json voor herhaalbare indelingen met meerdere indexen.