Introduzione

Greph è un motore di ricerca e rifattorizzazione in puro PHP per alberi di codice sorgente. Offre tre modalità correlate:

• Ricerca testuale con output compatibile con grep e l'usabilità di ripgrep.
• Ricerca AST con pattern strutturali PHP e metavariabili.
• Riscrittura AST con rifattorizzazione strutturale che preserva la formattazione.

Include anche modalità indicizzate precaricate per carichi di lavoro testuali e AST, criteri di aggiornamento basati sul ciclo di vita, gruppi di indici precaricati definiti da manifest e wrapper di compatibilità rg / sg per ambienti con strumenti e agenti.

Perché esiste Greph

Le applicazioni e gli agenti PHP che richiedono una ricerca rapida nel codice di solito ricorrono a strumenti nativi (grep, ripgrep, ast-grep), rinunciando alla portabilità e complicando la distribuzione. La ricerca e la riscrittura strutturali sono ancora più problematiche: di solito richiedono di uscire del tutto dal processo PHP.

Greph colma questa lacuna. Il vostro codice PHP può eseguire ricerche testuali, trovare corrispondenze strutturali e riscrivere il codice per rifattorizzarlo usando solo la libreria standard e nikic/php-parser. Output e codici di uscita sono compatibili con gli strumenti canonici, quindi gli script e gli agenti esistenti non devono cambiare.

Cosa fa

• Ricerca testuale con stringhe letterali e regex, con modalità per parole intere, distinzione tra maiuscole e minuscole, contesto, conteggi e soli file
• Ricerca AST strutturale PHP con $VAR, $$$VARIADIC e metavariabili ripetute
• Riscrittura AST che preserva la formattazione, con modalità di prova, interattiva e di scrittura
• Indici testuali precaricati (trigrammi + posting degli identificatori) per carichi di lavoro ripetuti
• Indice precaricato dei fatti AST e ricerca AST memorizzata nella cache per query strutturali ripetute
• Indici precaricati con gestione del ciclo di vita: static, manual-refresh, opportunistic-refresh, strict-stale-check
• Ricerca multi-indice e per gruppi con nome negli archivi precaricati di testo, fatti AST e cache AST
• Diagnostica del pianificatore con --trace-plan ed etichette di origine dell'indice per le ricerche precaricate
• Wrapper di compatibilità ripgrep e ast-grep CLI basati sullo stesso motore
• Pool di worker paralleli basato su pcntl con ripiego su un singolo processo
• Analizzatore di file che rispetta gitignore e .grephignore, con rilevamento dei file binari

Requisiti

• PHP 8.2 o versioni successive
• ext-json, ext-ctype e ext-tokenizer, abilitati in quasi tutte le build di PHP
• ext-zlib per l'archivio AST nella cache (greph-index ast-cache)
• nikic/php-parser (l'unica dipendenza di Composer)

Le funzionalità principali di ricerca testuale e AST funzionano in puro PHP. I confronti facoltativi dei benchmark dipendono da strumenti esterni come rg, grep e sg, ma Greph non ne ha bisogno per funzionare. Le scansioni parallele usano ext-pcntl quando disponibile e passano senza problemi a un singolo processo quando non lo è. Gli host che vietano proc_open() e shell_exec() sono descritti in Host con processi limitati.

Esempio rapido

Gli eseguibili vendor/bin richiedono Greph 0.2.3 o versioni successive quando Greph è installato come dipendenza del progetto.

# 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',
);

Iniziate con Per iniziare, poi consultate CLI e API per le altre funzionalità. Le sezioni Modalità, Indicizzazione e Compatibilità approfondiscono flussi di lavoro specifici.