# Kezdő lépések ## Telepítés A Greph telepítése ezzel: Composer: ```bash composer require greph/greph ``` Ez telepíti a könyvtárat és a négy végrehajtható fájlt ide: `vendor/bin/`: - `greph`: natív szövegkeresés, AST-keresés és AST-átírás - `greph-index`: bemelegített szövegindex, AST-tényindex és gyorsítótárazott AST-keresés - `rg`: ripgrep-stílusú kompatibilitási burkoló - `sg`: ast-grep-stílusú kompatibilitási burkoló Ezek a végrehajtható fájlok a projekt `vendor/bin/` könyvtárából működnek, mivel a Greph 0.2.3 verziója már telepítve van. A korábbi kiadások csak a Greph tároló klónján belül találták meg a Composer autoloaderét, ezért legalább ezt a verziót telepítse: ```bash composer require greph/greph:^0.2.3 ``` ## Követelmények - **PHP 8.2+** readonly osztályokhoz, enumokhoz, első osztályú hívható szintaxishoz és konstruktorpromócióhoz - **ext-json** a JSON kimenethez és a lemezen tárolt indexadatokhoz - **ext-ctype** a minták és beállítások feldolgozásához - **ext-tokenizer** a PHP-Parser és az AST-előszűrőkhöz - **ext-zlib** a gyorsítótárazott AST-tárolóhoz (`greph-index ast-cache`) - **nikic/php-parser** (automatikusan, Composer függőségként települ) A `ext-json`, a `ext-ctype` és a `ext-tokenizer` szinte minden PHP-buildben engedélyezve van. A `composer.json` jelenleg csak a `ext-json`-t deklarálja ([#5](https://github.com/inline0/greph/issues/5)), ezért a Composer nem jelez figyelmeztetést, ha a többi valamelyike hiányzik. Opcionális: - **ext-pcntl** párhuzamos vizsgálatokhoz. A Greph hiányában is zökkenőmentesen, egyetlen folyamatban fut tovább. - Külső `rg`, `grep` és `sg` binárisok az összehasonlító mérésekhez. Futás közben soha nincs rájuk szükség. A keresés, az átírás és az indexelés soha nem hívja meg a `proc_open()`-t vagy a `shell_exec()`-t; csak a párhuzamos vizsgálatok indítanak új folyamatokat, és `pcntl_fork()` nélkül egyetlen folyamatra állnak vissza. A [Folyamatkorlátozott hosztok](https://greph.inline0.dev/hu/docs/advanced/process-restricted-hosts) oldalon olyan hosztokról olvashat, amelyek letiltják a `proc_open()`, a `shell_exec()` vagy a `pcntl_fork()` használatát. ## Az első szöveges keresés A Greph alapértelmezett módja a grep-kompatibilis szöveges keresés: ```bash vendor/bin/greph -F "function" src ``` A kimenet a kanonikus `file:line:content` formátumot használja, amelyet a grep, a ripgrep és a legtöbb szerkesztőintegráció elvár. ```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( ``` Adja hozzá a `-i` kapcsolót a kis- és nagybetűktől független egyezéshez, a `-w` kapcsolót a teljes szavak egyezéséhez, a `-c` kapcsolót a találatok számához, a `-l` kapcsolót csak fájlútvonalak megjelenítéséhez, a `-C 2` kapcsolót két sornyi környezethez, és így tovább. A kapcsolók teljes listája a [CLI referenciában](https://greph.inline0.dev/hu/docs/cli) található. ## Az első AST-keresés Adja meg a `-p` kapcsolót és egy PHP alakú mintát a strukturális kereséshez: ```bash vendor/bin/greph -p 'new $CLASS()' src ``` A `$CLASS` egy met változó, amely bármilyen osztálynevet rögzít. A `new $CLASS()` minta minden argumentum nélküli `new` kifejezésre illeszkedik, az osztálytól, formázástól és megjegyzésektől függetlenül. Használja a `new $CLASS($$$ARGS)` mintát bármilyen argumentumú hívások egyeztetéséhez. Minden AST-találatnál a fájl, a kezdősor és az egyező kód jelenik meg: ```text src/Greph.php:43:new FileWalker() src/Greph.php:52:new TextSearchOptions() src/Greph.php:54:new TextSearcher() ``` További hasznos minták: ```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 ``` A teljes mintaszintaxist a [Módok / AST-keresés](https://greph.inline0.dev/hu/docs/modes/ast) oldalon találja. ## Az első átírás Adja hozzá a `-r` kapcsolót az AST-keresés átírássá alakításához: ```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 ``` Az átírások a találaton kívül megőrzik a formázást: csak az egyező csomópont cserélődik le, a környező szóközök, behúzás és megjegyzések érintetlenek maradnak. Maga az egyező csomópont a sablonból újonnan kerül kiírásra, ezért a saját elrendezése egységesített lesz, és a benne lévő megjegyzés elveszhet. Részletekért lásd: [Módok / Átírás](https://greph.inline0.dev/hu/docs/modes/rewrite). ## PHP API A statikus `Greph\Greph` homlokzat ugyanazokat a műveleteket teszi elérhetővé, mint a 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"; } ``` A teljes felületet a [API](https://greph.inline0.dev/hu/docs/api) ismerteti. ## Indexelt keresés Az ismétlődő feladatoknál előnyt jelentenek a bemelegített indexek. Építse fel egyszer az indexet, majd kérdezze le többször: ```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 ``` Az indexek alapértelmezés szerint a projekt gyökérkönyvtárában, a `.greph-index`, a `.greph-ast-index` és a `.greph-ast-cache` helyen találhatók. Aktívan változó fához válasszon életciklus-profilt ahelyett, hogy minden bemelegített indexet egyformán kezelne: ```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 ``` A szokásos megoldás: - a stabil alapot tartsa `static` állapotban - az aktívan változó rétegeket tartsa `opportunistic-refresh` állapotban - a stale viselkedést a `stats --dry-refresh` segítségével vizsgálja meg ### Keresés több bemelegített indexben Egyetlen paranccsal több bemelegített indexben is kereshet: ```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 ``` ### Elnevezett indexkészletek Ha ezt rendszeresen végzi, mentse az elrendezést a `.greph-index-set.json` fájlba, és az ismétlődő kapcsolók helyett használja a készlet alparancsait: ```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)' . ``` ### Tervezői nyomkövetés Ha látni szeretné, hogyan szűkíti a bemelegített keresés a jelölteket, adja hozzá a `--trace-plan` kapcsolót: ```bash vendor/bin/greph-index search --trace-plan -F "function" . vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' . ``` A teljes, bemelegített munkafolyamatról lásd az [Indexelt / Szöveg](https://greph.inline0.dev/hu/docs/indexed/text) és az [Indexelt / AST](https://greph.inline0.dev/hu/docs/indexed/ast) oldalakat. ## Kompatibilitási burkolók Ha vannak olyan eszközei vagy ügynökei, amelyek már ripgrep vagy ast-grep formátumban kommunikálnak, egyszerűen helyezze be a burkolókat: ```bash vendor/bin/rg --json -F "function" src vendor/bin/sg --pattern 'new $CLASS()' src --lang php ``` Mindkét burkoló ugyanazt a motort használja, és próbákkal ellenőriztük őket az upstream binárisokkal szemben. Az ellenőrzött felületet a [Kompatibilitás / rg](https://greph.inline0.dev/hu/docs/compatibility/rg) és a [Kompatibilitás / sg](https://greph.inline0.dev/hu/docs/compatibility/sg) dokumentálja, a létrehozott [funkciómátrix](https://greph.inline0.dev/hu/docs/advanced/feature-matrix) pedig megismétli. ## Konfiguráció A Greph két lemezen tárolt konvenciót vesz figyelembe: - `.gitignore`: alapértelmezés szerint figyelembe veszi. A letiltásához adja meg a `--no-ignore` kapcsolót. - `.grephignore`: szintaxisa megegyezik a `.gitignore` szintaxisával, és arra épül rá. Hasznos az olyan eszközspecifikus kizárásokhoz, amelyeket nem szeretne verziókezelésbe tenni. Az alapértelmezett indexkönyvtárak a kiválasztott gyökérben a `.greph-index`, a `.greph-ast-index` és a `.greph-ast-cache`. Bármelyik `greph-index` alparancsnál felülbírálhatja őket a `--index-dir` kapcsolóval, vagy használhatja a `.greph-index-set.json` beállítást ismételhető, több indexre kiterjedő elrendezésekhez.