Inleiding

Greph is een zoek- en refactoring-engine voor bronmappen, volledig geschreven in PHP. De engine ondersteunt drie verwante modi:

• Tekst zoeken met grep-compatibele uitvoer en gebruiksgemak in de stijl van ripgrep.
• AST-zoeken met structurele patronen en metavariabelen van PHP.
• AST-herschrijven voor structurele refactorings met behoud van de opmaak.

De engine biedt ook opgewarmde geïndexeerde modi voor zowel tekst- als AST-taken, vernieuwingsbeleid op basis van de levenscyclus, opgewarmde indexsets op basis van manifesten en compatibiliteitswrappers voor rg en sg voor tools en agentomgevingen.

Waarom Greph bestaat

PHP-applicaties en agents die snel code moeten doorzoeken, gebruiken meestal native tools (grep, ripgrep, ast-grep) via de shell. Dat gaat ten koste van de draagbaarheid en maakt de implementatie omslachtiger. Voor structureel zoeken en herschrijven is dat nog erger: daarvoor moet je meestal de PHP-omgeving volledig verlaten.

Greph dicht dat gat. Je PHP-code kan tekst zoeken, structurele matches vinden en refactorings uitvoeren met alleen de standaardbibliotheek en nikic/php-parser. De uitvoer en afsluitcodes zijn compatibel met de canonieke tools, zodat bestaande scripts en agents niet aangepast hoeven te worden.

Wat het doet

• Tekst zoeken met vaste tekenreeksen en reguliere expressies, met opties voor hele woorden, hoofdletterongevoelig zoeken, context, aantallen en alleen bestanden
• Structureel PHP AST-zoeken met $VAR, $$$VARIADIC en herhaalde metavariabelen
• AST-herschrijvingen met behoud van de opmaak, met modi voor proefuitvoering, interactief gebruik en schrijven
• Opgewarmde tekstindexen (trigrammen + identifiervermeldingen) voor herhaalde taken
• Opgewarmde AST-feitenindex en gecacht AST-zoeken voor herhaalde structurele zoekopdrachten
• Opgewarmde indexen met levenscyclusbeheer: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Zoeken in meerdere indexen en benoemde sets in opgewarmde tekst-, AST-feiten- en AST-cacheopslag
• Plannerdiagnostiek met --trace-plan en labels voor de indexherkomst bij zoeken met opgewarmde indexen
• Compatibiliteitswrappers voor ripgrep en ast-grep CLI, ondersteund door dezelfde engine
• Parallelle workerpool op basis van pcntl, met terugval op één proces
• Bestandsverkenner die rekening houdt met gitignore en .grephignore, met detectie van binaire bestanden

Wat het vereist

• PHP 8.2 of hoger
• ext-json, ext-ctype en ext-tokenizer, ingeschakeld in bijna elke PHP-build
• ext-zlib voor de gecachte AST-opslag (greph-index ast-cache)
• nikic/php-parser (de enige afhankelijkheid van Composer)

De kernfuncties voor tekst en AST werken in zuiver PHP. Voor optionele benchmarkvergelijkingen zijn externe tools zoals rg, grep en sg nodig, maar Greph zelf heeft die niet nodig. Parallelle scans gebruiken ext-pcntl als dat beschikbaar is en vallen anders probleemloos terug op uitvoering met één proces. Hosts waarop proc_open() en shell_exec() verboden zijn, worden behandeld in Hosts met procesbeperkingen.

Snel voorbeeld

Voor de vendor/bin-uitvoerbare bestanden is Greph 0.2.3 of hoger vereist wanneer Greph als afhankelijkheid van je project is geïnstalleerd.

# 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',
);

Begin met Aan de slag en raadpleeg vervolgens CLI en API voor de rest van de functionaliteit. De secties Modi, Geïndexeerd en Compatibiliteit behandelen specifieke workflows in detail.