Úvod

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

Greph je čistě PHP engine pro vyhledávání a refaktorování zdrojových stromů. Nabízí tři související režimy:

Textové vyhledávání s výstupem kompatibilním s grep a ergonomií ve stylu ripgrep.
Vyhledávání AST se strukturálními vzory PHP a metavariablami.
Přepis AST se strukturálním refaktorováním, které zachovává formátování.

Nabízí také připravené indexované režimy pro textové i AST úlohy, zásady obnovy zohledňující životní cyklus, sady připravených indexů podložené manifestem a obaly kompatibility rg / sg pro prostředí nástrojů a agentů.

Proč Greph vznikl

Aplikace PHP a agenti, kteří potřebují rychlé vyhledávání v kódu, obvykle spouštějí nativní nástroje z příkazového řádku (grep, ripgrep, ast-grep), čímž se vzdávají přenositelnosti a komplikují nasazení. Strukturální vyhledávání a přepis jsou na tom ještě hůř: obvykle vyžadují opustit proces PHP úplně.

Greph tuto mezeru odstraňuje. Váš kód PHP může provádět textové vyhledávání, strukturální porovnávání i refaktoringové přepisy pouze pomocí standardní knihovny a nikic/php-parser. Výstup i návratové kódy jsou kompatibilní s kanonickými nástroji, takže stávající skripty a agenti nevyžadují úpravy.

Co umí

Vyhledávání textu pomocí pevných řetězců a regulárních výrazů, včetně režimů celých slov, bez rozlišování velikosti písmen, s kontextem, počty a pouze se soubory
Strukturální vyhledávání AST PHP pomocí $VAR, $$$VARIADIC a opakovaných metavariabel
Přepis AST se zachováním formátování, v režimu náhledu, interaktivním režimu i režimu zápisu
Připravené textové indexy (trigramy a seznamy výskytů identifikátorů) pro opakované úlohy
Připravený index faktů AST a vyhledávání AST v mezipaměti pro opakované strukturální dotazy
Připravené indexy s životním cyklem: static, manual-refresh, opportunistic-refresh, strict-stale-check
Vyhledávání ve více indexech a pojmenovaných sadách napříč připravenými úložišti textu, faktů AST a mezipamětí AST
Diagnostika plánovače pomocí --trace-plan a označování původu indexu při připraveném vyhledávání
Obaly kompatibility ripgrep a ast-grep CLI využívající stejný engine
Paralelní fond pracovních procesů založený na pcntl s náhradním jednovláknovým režimem
Procházení souborů respektující gitignore a .grephignore s detekcí binárních souborů

Co vyžaduje

PHP 8.2 nebo novější
ext-json, ext-ctype a ext-tokenizer, které jsou povoleny téměř v každé sestavě PHP
ext-zlib pro úložiště AST v mezipaměti (greph-index ast-cache)
nikic/php-parser (jediná závislost Composer)

Základní textové funkce a funkce AST běží v čistém PHP. Volitelné srovnání výkonu závisí na externích nástrojích, jako jsou rg, grep a sg, samotné Greph je však ke svému fungování nepotřebuje. Paralelní skenování využívá ext-pcntl, je-li k dispozici, jinak bez problémů přejde na jeden proces. Hostitelům, kteří zakazují proc_open() a shell_exec(), se věnuje stránka Hostitelé s omezenými procesy.

Rychlý příklad

Spustitelné soubory vendor/bin vyžadují Greph 0.2.3 nebo novější, pokud je Greph nainstalován jako závislost vašeho projektu.

Shell

# 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

PHP

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čněte částí Začínáme a pak si projděte CLI a API, kde najdete zbytek funkcí. Konkrétní postupy podrobně popisují části Režimy, Indexované a Kompatibilita.