Kezdő lépések

Telepítés

A Greph telepítése ezzel: Composer:

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:

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), 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 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:

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.

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 található.

Az első AST-keresés

Adja meg a -p kapcsolót és egy PHP alakú mintát a strukturális kereséshez:

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:

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

További hasznos minták:

# 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 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:

# 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.

PHP API

A statikus Greph\Greph homlokzat ugyanazokat a műveleteket teszi elérhetővé, mint a CLI:

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 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:

# 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:

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:

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:

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:

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 és az Indexelt / 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:

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 és a Kompatibilitás / sg dokumentálja, a létrehozott funkciómátrix 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.