Introduktion

Greph er en søge- og omstruktureringsmotor til kildekodetræer, skrevet udelukkende i PHP. Den understøtter tre beslægtede tilstande:

• Tekstsøgning med grep-kompatibelt output og ripgrep-lignende brugervenlighed.
• AST-søgning med strukturelle PHP-mønstre og metavariabler.
• AST-omskrivning med strukturel omstrukturering, der bevarer formateringen.

Den indeholder også indekserede tilstande med opvarmede indekser til både tekst- og AST-arbejdsbelastninger, opdateringspolitikker, der tager højde for livscyklussen, sæt af opvarmede indekser baseret på manifestfiler samt kompatibilitetswrappere til rg og sg til værktøjs- og agentmiljøer.

Hvorfor Greph findes

PHP-applikationer og agenter, der har brug for hurtig kodesøgning, bruger typisk native værktøjer (grep, ripgrep, ast-grep). Det går ud over portabiliteten og gør udrulningen mere besværlig. Strukturel søgning og omskrivning er endnu vanskeligere: Det kræver normalt, at man forlader PHP-processen helt.

Greph lukker det hul. Din PHP-kode kan udføre tekstsøgninger, strukturelle matches og omstrukturerende omskrivninger med kun standardbiblioteket og nikic/php-parser. Output og afslutningskoder er kompatible med de kanoniske værktøjer, så eksisterende scripts og agenter ikke behøver at blive ændret.

Funktioner

• Tekstsøgning med faste strenge og regulære udtryk samt søgning efter hele ord, søgning uden forskel på store og små bogstaver, kontekst, antal og kun filer
• Strukturel PHP-AST-søgning med $VAR, $$$VARIADIC og gentagne metavariabler
• AST-omskrivning, der bevarer formateringen, med tilstande for prøve, interaktiv brug og skrivning
• Opvarmede tekstindekser (trigram- og identifikator-posteringer) til gentagne arbejdsbelastninger
• Opvarmet AST-faktaindeks og cachelagret AST-søgning til gentagne strukturelle forespørgsler
• Opvarmede indekser med livscyklusstyring: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Søgning i flere indekser og navngivne sæt på tværs af opvarmede tekst-, AST-fakta- og AST-cachelagre
• Diagnostik af planlæggeren med --trace-plan og mærkning af indeksoprindelse ved søgning i opvarmede indekser
• Kompatibilitetswrappere til ripgrep og ast-grep CLI, der bruger den samme motor
• Parallel arbejdspulje baseret på pcntl med fallback til én proces
• Filgennemgang med understøttelse af gitignore og .grephignore samt registrering af binærfiler

Krav

• PHP 8.2 eller nyere
• ext-json, ext-ctype og ext-tokenizer, som er aktiveret i næsten alle PHP-builds
• ext-zlib til det cachelagrede AST-lager (greph-index ast-cache)
• nikic/php-parser (den eneste Composer-afhængighed)

De grundlæggende tekst- og AST-funktioner kører i ren PHP. Valgfri benchmark-sammenligninger afhænger af eksterne værktøjer som rg, grep og sg, men Greph behøver dem ikke for at fungere. Parallelle scanninger bruger ext-pcntl, når det er tilgængeligt, og går ellers problemfrit over til kørsel i én proces. Værter, der forbyder proc_open() og shell_exec(), er beskrevet i Procesbegrænsede værter.

Hurtigt eksempel

De eksekverbare filer til vendor/bin kræver Greph 0.2.3 eller nyere, når Greph er installeret som en afhængighed af dit projekt.

# Text search
vendor/bin/greph -F "function" src

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

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

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

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

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

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

Start med Kom godt i gang, og brug derefter CLI og API for at gennemgå resten af funktionerne. Afsnittene Tilstande, Indekseret og Kompatibilitet gennemgår specifikke arbejdsgange i dybden.