Pierwsze kroki

Instalacja

Zainstaluj Greph za pomocą Composer:

composer require greph/greph

Spowoduje to zainstalowanie biblioteki i czterech plików wykonywalnych w vendor/bin/:

• greph: natywne wyszukiwanie tekstu, wyszukiwanie AST i przepisywanie AST
• greph-index: rozgrzany indeks tekstowy, indeks faktów AST i buforowane wyszukiwanie AST
• rg: warstwa zgodności w stylu ripgrep
• sg: warstwa zgodności w stylu ast-grep

Te pliki wykonywalne działają w katalogu vendor/bin/ projektu, ponieważ Greph 0.2.3. Wcześniejsze wydania znajdowały autoloader Composer tylko wewnątrz klonu repozytorium Greph, dlatego wymagana jest co najmniej ta wersja:

composer require greph/greph:^0.2.3

Wymagania

• PHP 8.2+ dla klas tylko do odczytu, wyliczeń, składni wywołań jako wartości pierwszej klasy i promocji parametrów konstruktora
• ext-json dla danych wyjściowych JSON i ładunków indeksu na dysku
• ext-ctype do analizowania wzorców i opcji
• ext-tokenizer dla PHP-Parser i filtrów wstępnych AST
• ext-zlib dla buforowanego magazynu AST (greph-index ast-cache)
• nikic/php-parser (instalowany automatycznie jako zależność Composer)

ext-json, ext-ctype i ext-tokenizer są włączone w niemal każdej kompilacji PHP. composer.json deklaruje obecnie tylko ext-json (#5), dlatego Composer nie ostrzega, gdy brakuje któregoś z pozostałych rozszerzeń.

Opcjonalnie:

• ext-pcntl do skanowania równoległego. Greph płynnie przechodzi na wykonanie w jednym procesie, gdy go brakuje.
• Zewnętrzne pliki binarne rg, grep i sg do porównań wydajności. Nigdy nie są wymagane w czasie działania.

Wyszukiwanie, przepisywanie i indeksowanie nigdy nie wywołują proc_open() ani shell_exec(); tylko skanowanie równoległe tworzy procesy potomne i przechodzi na jeden proces bez pcntl_fork(). Informacje o hostach, które wyłączają proc_open(), shell_exec() lub pcntl_fork(), znajdziesz w sekcji Hosty z ograniczeniami procesów.

Pierwsze wyszukiwanie tekstu

Domyślnym trybem Greph jest wyszukiwanie tekstu zgodne z grep:

vendor/bin/greph -F "function" src

Dane wyjściowe używają kanonicznego formatu file:line:content, którego oczekują grep, ripgrep i większość integracji z edytorami.

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(

Dodaj -i, aby dopasowywać bez rozróżniania wielkości liter, -w, aby dopasowywać całe słowa, -c, aby wyświetlać liczbę wyników, -l, aby zwracać tylko ścieżki plików, -C 2, aby uwzględnić dwa wiersze kontekstu, i tak dalej. Pełna lista znajduje się w dokumentacji CLIreferencyjnej.

Pierwsze wyszukiwanie AST

Przekaż -p i wzorzec o strukturze PHP, aby przełączyć się na wyszukiwanie strukturalne:

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

$CLASS to metazmienna, która przechwytuje dowolną nazwę klasy. Wzorzec new $CLASS() dopasowuje każde wyrażenie new bez argumentów, niezależnie od klasy, formatowania czy komentarzy. Użyj new $CLASS($$$ARGS), aby dopasować wywołania z dowolnymi argumentami.

Każde dopasowanie AST jest wyświetlane jako plik, numer początkowego wiersza i dopasowany kod:

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

Inne przydatne wzorce:

# 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

Pełny opis składni wzorców znajdziesz w sekcji Tryby / wyszukiwanie AST.

Pierwsze przepisywanie

Dodaj -r, aby zmienić wyszukiwanie AST w przepisywanie:

# 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

Poza dopasowaniem przepisywanie zachowuje format: zastępowany jest tylko dopasowany węzeł, a otaczające go białe znaki, wcięcia i komentarze pozostają nienaruszone. Sam dopasowany węzeł jest generowany na nowo z szablonu, więc jego układ zostaje ujednolicony, a komentarz wewnątrz niego może zniknąć. Szczegóły znajdziesz w sekcji Tryby / przepisywanie.

PHP API

Statyczna fasada Greph\Greph udostępnia te same operacje co 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";
}

Pełny zakres funkcji opisano w API.

Wyszukiwanie z indeksem

Powtarzające się zadania korzystają z rozgrzanych indeksów. Zbuduj indeks raz, a następnie wykonuj wiele zapytań:

# 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

Domyślnie indeksy znajdują się w katalogach .greph-index, .greph-ast-index i .greph-ast-cache w katalogu głównym projektu.

W przypadku aktywnie zmieniających się drzew wybierz profil cyklu życia zamiast traktować każdy rozgrzany indeks tak samo:

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

Typowy schemat wygląda tak:

• zachowaj stabilną bazę jako static
• zachowaj aktywnie zmieniające się nakładki jako opportunistic-refresh
• sprawdzaj zachowanie nieaktualnych danych za pomocą stats --dry-refresh

Wyszukiwanie z rozgrzanym indeksem wielokrotnym

Możesz przeszukać kilka rozgrzanych indeksów jednym poleceniem:

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

Zestawy indeksów o nazwach

Jeśli robisz to wielokrotnie, zapisz układ w .greph-index-set.json i używaj podpoleceń zestawu zamiast powtarzać flagi:

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)' .

Ślad planera

Aby zobaczyć, jak wyszukiwanie z rozgrzanym indeksem zawęża zbiór kandydatów, dodaj --trace-plan:

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

Pełny opis pracy z rozgrzanymi indeksami znajdziesz w sekcjach Indeksowanie / tekst i Indeksowanie / AST.

Warstwy zgodności

Jeśli masz narzędzia lub agentów, które już obsługują ripgrep lub ast-grep, użyj odpowiednich warstw:

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

Obie warstwy korzystają z tego samego silnika, a ich zgodność zweryfikowano sondami z użyciem oryginalnych plików binarnych. Zweryfikowany zakres opisano w sekcjach Zgodność / rg i Zgodność / sg oraz przedstawiono w wygenerowanej macierzy funkcji.

Konfiguracja

Greph uwzględnia dwie konwencje dotyczące plików na dysku:

• .gitignore: domyślnie respektowana. Przekaż --no-ignore, aby ją wyłączyć.
• .grephignore: ta sama składnia co .gitignore, stosowana dodatkowo. Przydatna do wykluczeń specyficznych dla narzędzia, których nie chcesz umieszczać w kontroli wersji.

Domyślne katalogi indeksów to .greph-index, .greph-ast-index i .greph-ast-cache w wybranym katalogu głównym. Zmień je za pomocą --index-dir w dowolnym podpoloeceniu greph-index albo użyj .greph-index-set.json, aby skonfigurować powtarzalne układy wielu indeksów.