# Primii pași ## Instalare Instalați Greph prin Composer: ```bash composer require greph/greph ``` Aceasta instalează biblioteca și patru executabile în `vendor/bin/`: - `greph`: căutare text nativă, căutare AST și rescriere AST - `greph-index`: index de text încălzit, index de fapte AST și căutare AST memorată în cache - `rg`: wrapper de compatibilitate în stilul ripgrep - `sg`: wrapper de compatibilitate în stilul ast-grep Aceste executabile funcționează din `vendor/bin/` proiectului dumneavoastră, deoarece Greph 0.2.3. Versiunile anterioare găseau autoloaderul Composer doar într-o clonă a depozitului Greph, așadar este necesară cel puțin acea versiune: ```bash composer require greph/greph:^0.2.3 ``` ## Cerințe - **PHP 8.2+** pentru clase readonly, enumuri, sintaxa callable de primă clasă și promovarea constructorilor - **ext-json** pentru ieșirea JSON și datele utile ale indexului de pe disc - **ext-ctype** pentru analizarea tiparelor și opțiunilor - **ext-tokenizer** pentru PHP-Parser și filtrele preliminare AST - **ext-zlib** pentru stocarea AST memorată în cache (`greph-index ast-cache`) - **nikic/php-parser** (instalat automat ca dependență Composer) `ext-json`, `ext-ctype` și `ext-tokenizer` sunt activate în aproape toate versiunile PHP. `composer.json` declară momentan doar `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), așa că Composer nu avertizează dacă lipsește una dintre celelalte. Opțional: - **ext-pcntl** pentru scanări paralele. Greph trece fără probleme la execuția cu un singur proces dacă extensia lipsește. - Binare `rg`, `grep` și `sg` externe pentru comparații de performanță. Nu sunt niciodată necesare la rulare. Căutarea, rescrierea și indexarea nu apelează niciodată `proc_open()` sau `shell_exec()`; doar scanările paralele creează procese separate și revin la un singur proces fără `pcntl_fork()`. Consultați [Gazde cu procese restricționate](https://greph.inline0.dev/ro/docs/advanced/process-restricted-hosts) pentru gazdele care dezactivează `proc_open()`, `shell_exec()` sau `pcntl_fork()`. ## Prima căutare de text Modul implicit al Greph este căutarea text compatibilă cu grep: ```bash vendor/bin/greph -F "function" src ``` Ieșirea folosește formatul canonic `file:line:content` așteptat de grep, ripgrep și de majoritatea integrărilor editorilor. ```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( ``` Adăugați `-i` pentru potriviri fără diferențiere între majuscule și minuscule, `-w` pentru potriviri ale cuvintelor întregi, `-c` pentru numărători, `-l` doar pentru căile fișierelor, `-C 2` pentru două linii de context și așa mai departe. Lista completă se găsește în [referințaCLI](https://greph.inline0.dev/ro/docs/cli). ## Prima căutare AST Transmiteți `-p` și un tipar în formatul PHP pentru a trece la căutarea structurală: ```bash vendor/bin/greph -p 'new $CLASS()' src ``` `$CLASS` este o metavariabilă care surprinde orice nume de clasă. Tiparul `new $CLASS()` se potrivește cu fiecare expresie `new` fără argumente, indiferent de clasă, formatare sau comentarii. Folosiți `new $CLASS($$$ARGS)` pentru a potrivi apeluri cu orice argumente. Fiecare potrivire AST este afișată ca fișier, linie de început și codul potrivit: ```text src/Greph.php:43:new FileWalker() src/Greph.php:52:new TextSearchOptions() src/Greph.php:54:new TextSearcher() ``` Alte tipare utile: ```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 ``` Consultați [Moduri / Căutare AST](https://greph.inline0.dev/ro/docs/modes/ast) pentru sintaxa completă a tiparelor. ## Prima rescriere Adăugați `-r` pentru a transforma căutarea AST într-o rescriere: ```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 ``` Rescrierile păstrează formatarea în afara potrivirii: se înlocuiește doar nodul potrivit, iar spațiile albe, indentarea și comentariile din jur rămân intacte. Nodul potrivit este generat din nou folosind șablonul, astfel că aspectul său este normalizat, iar un comentariu din interiorul lui se poate pierde. Consultați [Moduri / Rescriere](https://greph.inline0.dev/ro/docs/modes/rewrite) pentru detalii. ## PHP API Fațada statică `Greph\Greph` expune aceleași operații ca 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"; } ``` Întreaga suprafață este documentată în [API](https://greph.inline0.dev/ro/docs/api). ## Căutare indexată Volumul de lucru repetat beneficiază de indexuri încălzite. Construiți indexul o dată, apoi interogați-l de mai multe ori: ```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 ``` În mod implicit, indexurile se află în `.greph-index`, `.greph-ast-index` și `.greph-ast-cache` din rădăcina proiectului. Pentru arbori care se modifică activ, alegeți un profil de ciclu de viață în loc să tratați toate indexurile încălzite la fel: ```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 ``` Tiparul obișnuit este: - păstrați o bază stabilă ca `static` - păstrați suprapunerile care se modifică activ ca `opportunistic-refresh` - inspectați comportamentul elementelor învechite cu `stats --dry-refresh` ### Căutare încălzită în mai multe indexuri Puteți căuta în mai multe indexuri încălzite printr-o singură comandă: ```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 ``` ### Seturi de indexuri cu nume Dacă repetați acest lucru, definiți structura în `.greph-index-set.json` și folosiți subcomenzile setului în loc să repetați opțiunile: ```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)' . ``` ### Urmărirea planificatorului Pentru a vedea cum restrânge căutarea încălzită lista de candidați, adăugați `--trace-plan`: ```bash vendor/bin/greph-index search --trace-plan -F "function" . vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' . ``` Consultați [Indexat / Text](https://greph.inline0.dev/ro/docs/indexed/text) și [Indexat / AST](https://greph.inline0.dev/ro/docs/indexed/ast) pentru întregul flux de lucru încălzit. ## Wrapperi de compatibilitate Dacă aveți instrumente sau agenți care folosesc deja ripgrep sau ast-grep, adăugați wrapperii: ```bash vendor/bin/rg --json -F "function" src vendor/bin/sg --pattern 'new $CLASS()' src --lang php ``` Ambii wrapperi reutilizează același motor și sunt verificați prin testare cu binarele din amonte. Suprafața verificată este documentată în [Compatibilitate / rg](https://greph.inline0.dev/ro/docs/compatibility/rg) și [Compatibilitate / sg](https://greph.inline0.dev/ro/docs/compatibility/sg) și reprodusă în [matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix) generată. ## Configurare Greph recunoaște două convenții de pe disc: - `.gitignore`: respectat în mod implicit. Transmiteți `--no-ignore` pentru a dezactiva. - `.grephignore`: aceeași sintaxă ca `.gitignore`, aplicată suplimentar. Util pentru excluderi specifice instrumentului pe care nu doriți să le includeți în controlul versiunilor. Directoarele indexurilor implicite sunt `.greph-index`, `.greph-ast-index` și `.greph-ast-cache` la rădăcina aleasă. Suprascrieți cu `--index-dir` în orice subcomandă `greph-index` sau folosiți `.greph-index-set.json` pentru structuri reproductibile cu mai multe indexuri.