Začínáme

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

Instalace

Nainstalujte Greph pomocí Composer:

Shell

composer require greph/greph

Tím se nainstaluje knihovna a čtyři spustitelné soubory do vendor/bin/:

greph: nativní textové vyhledávání, vyhledávání v AST a přepis AST
greph-index: předehřátý textový index, index faktů AST a vyhledávání v AST s mezipamětí
rg: wrapper kompatibilní se stylem ripgrep
sg: wrapper kompatibilní se stylem ast-grep

Tyto spustitelné soubory fungují v adresáři vendor/bin/ vašeho projektu, protože Greph 0.2.3. Starší vydání našla zavaděč Composer pouze uvnitř klonu repozitáře Greph, proto použijte alespoň tuto verzi:

Shell

composer require greph/greph:^0.2.3

Požadavky

PHP 8.2+ pro readonly třídy, výčty, syntaxi callable na první úrovni a povýšení konstruktoru
ext-json pro výstup JSON a datové části indexu na disku
ext-ctype pro parsování vzorů a možností
ext-tokenizer pro PHP-Parser a předfiltry AST
ext-zlib pro úložiště AST v mezipaměti (greph-index ast-cache)
nikic/php-parser (instaluje se automaticky jako závislost Composer)

ext-json, ext-ctype a ext-tokenizer jsou povoleny téměř v každé sestavě PHP. composer.json momentálně deklaruje pouze ext-json (#5), takže Composer nevaruje, pokud některé z ostatních chybí.

Volitelné:

ext-pcntl pro paralelní skenování. Greph při jeho absenci bez problémů přejde na jednovláknové spuštění.
Externí binární soubory rg, grep a sg pro srovnání výkonu. Za běhu nejsou nikdy potřeba.

Vyhledávání, přepisování a indexování nikdy nevolají proc_open() ani shell_exec(); pouze paralelní skenování vytváří procesy a bez pcntl_fork() přejde na jeden proces. Hostitelům, kteří zakazují proc_open(), shell_exec() nebo pcntl_fork(), se věnuje stránka Hostitelé s omezenými procesy.

První textové vyhledávání

Výchozím režimem Greph je textové vyhledávání kompatibilní s grep:

Shell

vendor/bin/greph -F "function" src

Výstup používá kanonický formát file:line:content, který očekávají grep, ripgrep a většina integrací editorů.

Text

src/Greph.php:41:    public static function walk(string|array $paths, ?WalkOptions $options = null): FileList
src/Greph.php:50:    public static function searchText(string $pattern, string|array $paths, ?TextSearchOptions $options = null): array
src/Greph.php:81:    public static function buildTextIndex(

Přidejte -i pro rozlišování velikosti písmen, -w pro celá slova, -c pro počty, -l pouze pro cesty k souborům, -C 2 pro dva kontextové řádky a další. Úplný seznam najdete v referenci CLI.

První vyhledávání AST

Přepněte na strukturální vyhledávání předáním -p a vzoru ve tvaru PHP:

Shell

vendor/bin/greph -p 'new $CLASS()' src

$CLASS je metavariabla, která zachytí libovolný název třídy. Vzor new $CLASS() odpovídá každému výrazu new bez argumentů bez ohledu na třídu, formátování nebo komentáře. Pomocí new $CLASS($$$ARGS) odpovídáte voláním s libovolnými argumenty.

Každá shoda AST se vypíše jako soubor, počáteční řádek a odpovídající kód:

Text

src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()

Další užitečné vzory:

Shell

# Any method call with any arguments
vendor/bin/greph -p '$obj->$method($$$ARGS)' src

# Any function declaration with a void return type
vendor/bin/greph -p 'function $name($$$PARAMS): void {}' src

# Old-style array calls
vendor/bin/greph -p 'array($$$ITEMS)' src

Úplnou syntaxi vzorů najdete v části Režimy / vyhledávání AST.

První přepis

Přidáním -r změníte vyhledávání AST na přepis:

Shell

# Preview only
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

# Apply
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' src

# Confirm each file before writing
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Při přepisu se mimo shodu zachovává formátování: nahradí se pouze odpovídající uzel a okolní mezery, odsazení i komentáře zůstanou nedotčené. Samotný uzel se znovu vytvoří ze šablony, takže se jeho vlastní rozložení normalizuje a komentář uvnitř něj může být ztracen. Podrobnosti najdete v části Režimy / přepis.

PHP API

Statická fasáda Greph\Greph nabízí stejné operace jako CLI:

PHP

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Text\TextSearchOptions;

$results = Greph::searchText(
    'function',
    'src',
    new TextSearchOptions(fixedString: true, caseInsensitive: true),
);

foreach ($results as $file) {
    foreach ($file->matches as $match) {
        echo "{$file->file}:{$match->line}:{$match->content}\n";
    }
}

$matches = Greph::searchAst(
    'new $CLASS()',
    'src',
    new AstSearchOptions(),
);

foreach ($matches as $match) {
    echo "{$match->file}:{$match->startLine}:{$match->code}\n";
}

Úplný přehled rozhraní najdete v API.

Indexované vyhledávání

Opakované úlohy těží z připravených indexů. Vytvořte index jednou a pak se opakovaně dotazujte:

Shell

# Text index
vendor/bin/greph-index build .
vendor/bin/greph-index search -F "function" .

# AST fact index
vendor/bin/greph-index ast-index build .
vendor/bin/greph-index ast-index search 'new $CLASS()' src

# Cached parsed-tree index
vendor/bin/greph-index ast-cache build .
vendor/bin/greph-index ast-cache search 'array($$$ITEMS)' src

Ve výchozím nastavení jsou indexy v kořeni projektu v adresářích .greph-index, .greph-ast-index a .greph-ast-cache.

U často se měnících stromů zvolte profil životního cyklu, místo abyste se ke všem připraveným indexům chovali stejně:

Shell

vendor/bin/greph-index build . --lifecycle static
vendor/bin/greph-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
vendor/bin/greph-index stats . --dry-refresh

Obvyklý postup:

stabilní základ udržujte jako static
často se měnící překryvné vrstvy udržujte jako opportunistic-refresh
zastaralé chování zkontrolujte pomocí stats --dry-refresh

Vyhledávání v několika připravených indexech

V jednom příkazu můžete prohledat několik připravených indexů:

Shell

vendor/bin/greph-index search -F "apply_filters" . \
  --index-dir wordpress/.greph-index \
  --index-dir wp-content/plugins/my-plugin/.greph-index \
  --show-index-origin

vendor/bin/greph-index ast-index search 'new $CLASS()' . \
  --index-dir wordpress/.greph-ast-index \
  --index-dir wp-content/plugins/my-plugin/.greph-ast-index \
  --show-index-origin

Pojmenované sady indexů

Pokud to děláte opakovaně, zapište rozložení do .greph-index-set.json a místo opakovaného zadávání příznaků použijte dílčí příkazy pro sady:

Shell

vendor/bin/greph-index set build
vendor/bin/greph-index set stats --dry-refresh
vendor/bin/greph-index set search --show-index-origin -F "apply_filters" .
vendor/bin/greph-index set search --mode ast-index 'new $CLASS()' .
vendor/bin/greph-index set search --mode ast-cache 'array($$$ITEMS)' .

Trasování plánovače

Chcete-li zjistit, jak připravené vyhledávání zužuje výběr kandidátů, přidejte --trace-plan:

Shell

vendor/bin/greph-index search --trace-plan -F "function" .
vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' .

Úplný postup pro připravené vyhledávání najdete v částech Indexované / text a Indexované / AST.

Obaly pro kompatibilitu

Pokud už máte nástroje nebo agenty, které pracují s ripgrep nebo ast-grep, stačí přidat obaly:

Shell

vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php

Oba obaly znovu používají stejný engine a jejich chování bylo ověřeno sondami proti původním binárním souborům. Ověřené možnosti jsou popsány v částech Kompatibilita / rg a Kompatibilita / sg a zopakovány ve vygenerované matici funkcí.

Konfigurace

Greph přebírá dvě konvence pro soubory na disku:

.gitignore: standardně se respektuje. Zakážete to pomocí --no-ignore.
.grephignore: stejná syntaxe jako .gitignore, použije se navíc. Hodí se pro vyloučení specifická pro nástroj, která nechcete verzovat.

Výchozí adresáře indexů jsou ve zvoleném kořeni .greph-index, .greph-ast-index a .greph-ast-cache. Přepsat je můžete pomocí --index-dir v libovolném dílčím příkazu greph-index, případně použijte .greph-index-set.json pro opakovatelná rozložení s více indexy.