Treci la conținut

Primii pași

Vizualizați ca Markdown Editați pe GitHub Documentație la d105217

Instalare

Instalați Greph prin Composer:

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

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

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

Transmiteți -p și un tipar în formatul PHP pentru a trece la căutarea structurală:

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

Shell
# 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 pentru sintaxa completă a tiparelor.

Prima rescriere

Adăugați -r pentru a transforma căutarea AST într-o rescriere:

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

Volumul de lucru repetat beneficiază de indexuri încălzite. Construiți indexul o dată, apoi interogați-l de mai multe ori:

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

Shell
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

Puteți căuta în mai multe indexuri încălzite printr-o singură comandă:

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

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

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

Consultați Indexat / Text și Indexat / 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:

Shell
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 și Compatibilitate / sg și reprodusă în matricea de funcționalități 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.