Wprowadzenie

Greph to napisany w czystym PHP silnik wyszukiwania i refaktoryzacji drzew źródłowych. Obsługuje trzy powiązane tryby:

• Wyszukiwanie tekstu z danymi wyjściowymi zgodnymi z grep i ergonomią w stylu ripgrep.
• Wyszukiwanie AST ze wzorcami strukturalnymi PHP i metazmiennymi.
• Przepisywanie AST z refaktoryzacją strukturalną zachowującą formatowanie.

Udostępnia również rozgrzane tryby indeksowania dla zadań tekstowych i AST, zasady odświeżania uwzględniające cykl życia, zestawy rozgrzanych indeksów oparte na manifeście oraz warstwy zgodności rg / sg dla narzędzi i środowisk agentów.

Dlaczego powstało Greph

Aplikacje PHP i agenci, którzy potrzebują szybkiego wyszukiwania kodu, zwykle uruchamiają natywne narzędzia powłoki (grep, ripgrep, ast-grep), tracąc przenośność i utrudniając wdrożenie. Wyszukiwanie strukturalne i przepisywanie są jeszcze trudniejsze: zazwyczaj wymagają całkowitego opuszczenia procesu PHP.

Greph usuwa tę lukę. Kod PHP może wykonywać wyszukiwanie tekstowe, dopasowywać struktury i przepisywać kod w ramach refaktoryzacji, korzystając wyłącznie ze standardowej biblioteki i nikic/php-parser. Dane wyjściowe i kody zakończenia są zgodne z kanonicznymi narzędziami, więc istniejące skrypty i agenci nie wymagają zmian.

Funkcje

• Wyszukiwanie tekstu za pomocą stałych ciągów i wyrażeń regularnych, z dopasowywaniem całych słów, bez rozróżniania wielkości liter, wyświetlaniem kontekstu, zliczaniem wyników i trybem tylko ścieżek plików
• Strukturalne wyszukiwanie AST PHP z użyciem $VAR, $$$VARIADIC i powtarzanych metazmiennych
• Przepisywanie AST zachowujące formatowanie z trybami symulacji, interaktywnym i zapisu
• Rozgrzane indeksy tekstowe (trygramy + listy identyfikatorów) do powtarzających się zadań
• Rozgrzany indeks faktów AST i buforowane wyszukiwanie AST do powtarzających się zapytań strukturalnych
• Rozgrzane indeksy uwzględniające cykl życia: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Wyszukiwanie obejmujące wiele indeksów i zestawów o nazwach w rozgrzanych magazynach tekstu, faktów AST i buforowanych drzew AST
• Diagnostyka planera z użyciem --trace-plan i etykietami pochodzenia indeksu dla wyszukiwania z rozgrzanym indeksem
• Warstwy zgodności ripgrep i ast-grep CLI obsługiwane przez ten sam silnik
• Równoległa pula procesów roboczych oparta na pcntl z możliwością przejścia na jeden proces
• Obsługujący gitignore i .grephignore moduł przeglądania plików z wykrywaniem plików binarnych

Wymagania

• PHP 8.2 lub nowszy
• ext-json, ext-ctype i ext-tokenizer, włączone w niemal każdej kompilacji PHP
• ext-zlib dla buforowanego magazynu AST (greph-index ast-cache)
• nikic/php-parser (jedyna zależność Composer)

Podstawowe funkcje tekstowe i AST działają w czystym PHP. Opcjonalne porównania wydajności wymagają zewnętrznych narzędzi, takich jak rg, grep i sg, ale samo Greph nie potrzebuje ich do działania. Skanowanie równoległe używa ext-pcntl, gdy jest dostępne, a w przeciwnym razie płynnie przechodzi na wykonanie w jednym procesie. Informacje o hostach, które blokują proc_open() i shell_exec(), znajdziesz w sekcji Hosty z ograniczeniami procesów.

Szybki przykład

Pliki wykonywalne vendor/bin wymagają Greph 0.2.3 lub nowszego, gdy Greph jest zainstalowane jako zależność projektu.

# Text search
vendor/bin/greph -F "function" src

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

# Structural rewrite preview
vendor/bin/greph -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src

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

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

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

$rewrites = Greph::rewriteAst(
    'array($$$ITEMS)',
    '[$$$ITEMS]',
    'src',
);

Zacznij od Pierwsze kroki, a następnie skorzystaj z sekcji CLI i API, aby poznać pozostałe funkcje. Sekcje Tryby, Indeksowanie i Zgodność szczegółowo opisują konkretne zastosowania.