# Začínáme ## Instalace Nainstalujte Greph pomocí Composer: ```bash 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: ```bash 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](https://github.com/inline0/greph/issues/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](https://greph.inline0.dev/cs/docs/advanced/process-restricted-hosts). ## První textové vyhledávání Výchozím režimem Greph je textové vyhledávání kompatibilní s grep: ```bash 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](https://greph.inline0.dev/cs/docs/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: ```bash 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: ```bash # 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](https://greph.inline0.dev/cs/docs/modes/ast). ## První přepis Přidáním `-r` změníte vyhledávání AST na přepis: ```bash # 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](https://greph.inline0.dev/cs/docs/modes/rewrite). ## 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](https://greph.inline0.dev/cs/docs/api). ## Indexované vyhledávání Opakované úlohy těží z připravených indexů. Vytvořte index jednou a pak se opakovaně dotazujte: ```bash # 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ě: ```bash 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ů: ```bash 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: ```bash 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`: ```bash 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](https://greph.inline0.dev/cs/docs/indexed/text) a [Indexované / AST](https://greph.inline0.dev/cs/docs/indexed/ast). ## Obaly pro kompatibilitu Pokud už máte nástroje nebo agenty, které pracují s ripgrep nebo ast-grep, stačí přidat obaly: ```bash 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](https://greph.inline0.dev/cs/docs/compatibility/rg) a [Kompatibilita / sg](https://greph.inline0.dev/cs/docs/compatibility/sg) a zopakovány ve vygenerované [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix). ## 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.