Įvadas

Greph – paieškos ir pertvarkymo variklis, veikiantis tik su PHP, skirtas šaltinio kodų medžiams. Jame yra trys susiję režimai:

• Teksto paieška su grep suderinama išvestimi ir ripgrep tipo naudojimo patogumu.
• AST paieška su PHP struktūriniais šablonais ir metakintamaisiais.
• AST perrašymas struktūriniam kodui pertvarkyti išsaugant formatavimą.

Taip pat pateikiami įkelti indeksuoti režimai teksto ir AST užduotims, atnaujinimo strategijos pagal gyvavimo ciklą, manifestais pagrįsti įkelti indeksų rinkiniai ir suderinamumo apvalkalai rg / sg, skirti įrankių ir agentų aplinkoms.

Kodėl atsirado Greph

PHP programos ir agentai, kuriems reikia greitai ieškoti kode, paprastai iškviečia savąsias priemones (grep, ripgrep, ast-grep), taip atsisakydami perkeliamumo ir apsunkindami diegimą. Struktūrinei paieškai ir perrašymui reikia dar daugiau: paprastai tenka visiškai išeiti iš PHP proceso.

Greph panaikina šį trūkumą. Jūsų PHP kodas gali vykdyti teksto paieškas, ieškoti struktūrinių atitikčių ir perrašyti kodą naudodamas tik standartinę biblioteką bei nikic/php-parser. Išvestis ir išėjimo kodai suderinami su įprastomis priemonėmis, todėl esamų scenarijų ir agentų keisti nereikia.

Ką jis daro

• Paieška pagal fiksuotą eilutę ir reguliarųjį reiškinį; galima ieškoti ištisų žodžių, neatsižvelgiant į raidžių dydį, nurodyti kontekstą, skaičiuoti atitiktis ir rodyti tik failus
• Struktūrinė PHP AST paieška su $VAR, $$$VARIADIC ir pasikartojančiais metakintamaisiais
• AST perrašymas išsaugant formatavimą, su peržiūros, interaktyviu ir įrašymo režimais
• Įkelti teksto indeksai (trigramų ir identifikatorių įrašai) pasikartojančioms užduotims
• Įkeltas AST faktų indeksas ir AST paieška podėlyje pasikartojančioms struktūrinėms užklausoms
• Įkelti indeksai, valdomi pagal gyvavimo ciklą: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Paieška keliuose indeksuose ir pavadintuose rinkiniuose, naudojant įkeltus teksto, AST faktų ir AST podėlio duomenis
• Planavimo diagnostika su --trace-plan ir indeksų kilmės žymėjimu įkeltų indeksų paieškose
• Suderinamumo apvalkalai ripgrep ir ast-grep CLI, paremti tuo pačiu varikliu
• Lygiagretus darbuotojų telkinys, paremtas pcntl, su atsarginiu veikimu viename procese
• Failų naršyklė, atsižvelgianti į gitignore ir .grephignore, atpažįstanti dvejetainius failus

Ko reikia

• PHP 8.2 arba naujesnės versijos
• ext-json, ext-ctype ir ext-tokenizer, įjungtų beveik kiekvienoje PHP versijoje
• ext-zlib podėlyje saugomai AST saugyklai (greph-index ast-cache)
• nikic/php-parser (vienintelė Composer priklausomybė)

Pagrindinės teksto ir AST funkcijos veikia tik su PHP. Pasirenkamiems palyginimams su etalonais reikia išorinių įrankių, pavyzdžiui, rg, grep ir sg, tačiau pačiam Greph jie nereikalingi. Lygiagrečioms paieškoms naudojamas ext-pcntl, jei jis prieinamas; kitu atveju sklandžiai pereinama prie vykdymo viename procese. Apie aplinkas, kuriose draudžiami proc_open() ir shell_exec(), skaitykite skiltyje Procesais apribotos prieglobos aplinkos.

Trumpas pavyzdys

Vykdomiesiems vendor/bin failams reikia Greph 0.2.3 ar naujesnės versijos, kai Greph įdiegiamas kaip jūsų projekto priklausomybė.

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

Pradėkite nuo skilties Darbo pradžia, tada susipažinkite su CLI ir API, kur rasite likusias funkcijas. Skiltyse Režimai, Indeksuota ir Suderinamumas išsamiai aprašytos konkrečios darbo eigos.