# Pierwsze kroki ## Instalacja Zainstaluj Greph za pomocą Composer: ```bash 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: ```bash 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](https://github.com/inline0/greph/issues/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](https://greph.inline0.dev/pl/docs/advanced/process-restricted-hosts). ## Pierwsze wyszukiwanie tekstu Domyślnym trybem Greph jest wyszukiwanie tekstu zgodne z grep: ```bash 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. ```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( ``` 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](https://greph.inline0.dev/pl/docs/cli). ## Pierwsze wyszukiwanie AST Przekaż `-p` i wzorzec o strukturze PHP, aby przełączyć się na wyszukiwanie strukturalne: ```bash 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: ```text src/Greph.php:43:new FileWalker() src/Greph.php:52:new TextSearchOptions() src/Greph.php:54:new TextSearcher() ``` Inne przydatne wzorce: ```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 ``` Pełny opis składni wzorców znajdziesz w sekcji [Tryby / wyszukiwanie AST](https://greph.inline0.dev/pl/docs/modes/ast). ## Pierwsze przepisywanie Dodaj `-r`, aby zmienić wyszukiwanie AST w przepisywanie: ```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 ``` 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](https://greph.inline0.dev/pl/docs/modes/rewrite). ## PHP API Statyczna fasada `Greph\Greph` udostępnia te same operacje co 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"; } ``` Pełny zakres funkcji opisano w [API](https://greph.inline0.dev/pl/docs/api). ## Wyszukiwanie z indeksem Powtarzające się zadania korzystają z rozgrzanych indeksów. Zbuduj indeks raz, a następnie wykonuj wiele zapytań: ```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 ``` 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: ```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 ``` 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: ```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 ``` ### 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: ```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)' . ``` ### Ślad planera Aby zobaczyć, jak wyszukiwanie z rozgrzanym indeksem zawęża zbiór kandydatów, dodaj `--trace-plan`: ```bash 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](https://greph.inline0.dev/pl/docs/indexed/text) i [Indeksowanie / AST](https://greph.inline0.dev/pl/docs/indexed/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: ```bash 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](https://greph.inline0.dev/pl/docs/compatibility/rg) i [Zgodność / sg](https://greph.inline0.dev/pl/docs/compatibility/sg) oraz przedstawiono w wygenerowanej [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix). ## 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.