Uvod

Greph je mehanizem za iskanje in preoblikovanje izvornih dreves v čistem PHP. Podpira tri sorodne načine:

• Iskanje po besedilu z izhodom, združljivim z grep, in ergonomijo v slogu ripgrep.
• Iskanje AST s strukturnimi vzorci PHP in metaspremenljivkami.
• Prepis AST s strukturnim preoblikovanjem, ki ohranja oblikovanje.

Vključuje tudi ogrete indeksirane načine za besedilna opravila in opravila AST, pravilnike osveževanja, prilagojene življenjskemu ciklu, ogrete nabore indeksov, podprte z manifestom, ter ovojnice za združljivost rg / sg za orodja in agentska okolja.

Zakaj obstaja Greph

Aplikacije in agenti PHP, ki potrebujejo hitro iskanje po kodi, običajno zaženejo izvorna orodja v lupini (grep, ripgrep, ast-grep), s čimer izgubijo prenosljivost in si otežijo uvajanje. Strukturno iskanje in prepisovanje sta še zahtevnejša: običajno je treba povsem zapustiti proces PHP.

Greph odpravi to vrzel. Vaša koda PHP lahko išče po besedilu, išče strukturna ujemanja in prepisuje refaktorirano kodo samo s standardno knjižnico in nikic/php-parser. Izhod in izhodne kode so združljivi s kanoničnimi orodji, zato obstoječih skriptov in agentov ni treba spreminjati.

Kaj omogoča

• Iskanje po nespremenljivih nizih in regularnih izrazih z načini za cele besede, neobčutljivost na velikost črk, kontekst, štetje in samo datoteke
• Strukturno iskanje AST PHP z $VAR, $$$VARIADIC in ponovljenimi metaspremenljivkami
• Prepis AST, ki ohranja oblikovanje, z načini za suhi zagon, interaktivno uporabo in zapis
• Ogreti besedilni indeksi (tri-grami in pojavnice identifikatorjev) za ponavljajoča se opravila
• Ogreti indeks dejstev AST in predpomnjeno iskanje AST za ponavljajoče se strukturne poizvedbe
• Ogreti indeksi, prilagojeni življenjskemu ciklu: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Iskanje po več indeksih in poimenovanih naborih v ogretih besedilnih indeksih, indeksih dejstev AST in shrambah predpomnilnika AST
• Diagnostika načrtovalnika z --trace-plan in označevanjem izvora indeksa pri ogretem iskanju
• Ovojnici za združljivost ripgrep in ast-grep CLI, ki uporabljata isti mehanizem
• Nabor vzporednih delavcev na osnovi pcntl z nadomestnim izvajanjem v enem procesu
• Pregledovalnik datotek, ki upošteva gitignore in .grephignore ter zazna binarne datoteke

Kaj zahteva

• PHP 8.2 ali novejši
• ext-json, ext-ctype in ext-tokenizer, ki so omogočeni v skoraj vsaki gradnji PHP
• ext-zlib za predpomnjeno shrambo AST (greph-index ast-cache)
• nikic/php-parser (edina odvisnost Composer)

Osrednje funkcije za besedilo in AST delujejo v čistem PHP. Izbirne primerjave zmogljivosti so odvisne od zunanjih orodij, kot so rg, grep in sg, vendar jih Greph za delovanje ne potrebuje. Vzporedna pregledovanja uporabljajo ext-pcntl, kadar je na voljo, sicer pa nemoteno preklopijo na izvajanje v enem procesu. Gostitelji, ki prepovedujejo proc_open() in shell_exec(), so obravnavani v razdelku Gostitelji z omejenimi procesi.

Kratek primer

Izvršne datoteke vendor/bin potrebujejo Greph 0.2.3 ali novejši, če je Greph nameščen kot odvisnost vašega projekta.

# 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 z Uvodom, nato pa za preostale funkcije uporabite CLI in API. Razdelki Načini, Indeksiranje in Združljivost podrobno obravnavajo posamezne poteke dela.