Úvod

Greph je čistý nástroj na vyhľadávanie a refaktorovanie zdrojových stromov v PHP. Ponúka tri súvisiace režimy:

• Textové vyhľadávanie s výstupom kompatibilným s grep a používateľským prostredím v štýle ripgrep.
• Vyhľadávanie v AST so štrukturálnymi vzormi PHP a metavariabilnými premennými.
• Prepisovanie AST so štrukturálnym refaktorovaním, ktoré zachováva formátovanie.

Obsahuje aj zahriate indexované režimy pre textové aj AST úlohy, pravidlá obnovovania zohľadňujúce životný cyklus, súpravy zahriatych indexov založené na manifeste a obaly kompatibilné s rg a sg pre nástroje a agentov.

Prečo existuje Greph

Aplikácie PHP a agenti, ktorí potrebujú rýchlo vyhľadávať v kóde, zvyčajne spúšťajú natívne nástroje cez shell (grep, ripgrep, ast-grep), čím sa vzdávajú prenositeľnosti a komplikujú nasadenie. So štrukturálnym vyhľadávaním a prepisovaním je to ešte horšie: zvyčajne si vyžaduje úplne opustiť proces PHP.

Greph túto medzeru vypĺňa. Váš kód PHP môže vykonávať textové vyhľadávania, štrukturálne porovnávanie a refaktoračné prepisovanie iba pomocou štandardnej knižnice a nikic/php-parser. Výstup a návratové kódy sú kompatibilné s kanonickými nástrojmi, takže existujúce skripty a agentov netreba meniť.

Čo dokáže

• Textové vyhľadávanie presných reťazcov a regulárnych výrazov s režimami pre celé slová, nerozlišovanie veľkosti písmen, kontext, počet zhôd a vyhľadávanie iba v názvoch súborov
• Štrukturálne vyhľadávanie v AST PHP pomocou $VAR, $$$VARIADIC a opakovaných metavariabilných premenných
• Prepisovanie AST so zachovaním formátovania v režimoch skúšobného spustenia, interaktívneho režimu a zápisu
• Zahriate textové indexy (trigramy a zoznamy výskytov identifikátorov) pre opakované úlohy
• Zahriaty index faktov AST a vyhľadávanie v AST s vyrovnávacou pamäťou pre opakované štrukturálne dopyty
• Zahriate indexy so zohľadnením životného cyklu: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Vyhľadávanie vo viacerých indexoch a pomenovaných súpravách v zahriatych úložiskách textu, faktov AST a vyrovnávacej pamäte AST
• Diagnostika plánovača pomocou --trace-plan a označovanie pôvodu indexu pri vyhľadávaní so zahriatymi indexmi
• Obaly kompatibilné s ripgrep a ast-grep CLI, ktoré využívajú rovnaký nástroj
• Paralelná skupina pracovníkov založená na pcntl s náhradným režimom jedného procesu
• Prehliadač súborov, ktorý zohľadňuje gitignore a .grephignore a rozpoznáva binárne súbory

Čo vyžaduje

• PHP 8.2 alebo novší
• ext-json, ext-ctype a ext-tokenizer, ktoré sú povolené takmer v každom zostavení PHP
• ext-zlib pre úložisko AST s vyrovnávacou pamäťou (greph-index ast-cache)
• nikic/php-parser (jediná závislosť Composer)

Základné funkcie pre text a AST fungujú v čistom PHP. Voliteľné porovnávanie benchmarkov závisí od externých nástrojov, ako sú rg, grep a sg, no samotný Greph na ich fungovanie nepotrebuje. Pri paralelnom skenovaní sa v prípade dostupnosti používa ext-pcntl, inak sa bez problémov prejde na vykonávanie v jednom procese. Hostiteľom, ktoré zakazujú proc_open() a shell_exec(), sa venuje časť Hostitelia s obmedzenými procesmi.

Rýchly príklad

Na spustenie spustiteľných súborov vendor/bin potrebujete Greph 0.2.3 alebo novší, ak je Greph nainštalovaný ako závislosť vášho projektu.

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

Začnite časťou Začíname a potom si v častiach CLI a API pozrite zvyšok funkcií. Časti Režimy, Indexovanie a Kompatibilita podrobne opisujú konkrétne pracovné postupy.