# 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](https://greph.inline0.dev/it/docs/advanced/process-restricted-hosts).

## Esempio rapido

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

```bash
# 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
```

```php
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](https://greph.inline0.dev/it/docs/getting-started), poi consultate [CLI](https://greph.inline0.dev/it/docs/cli) e [API](https://greph.inline0.dev/it/docs/api) per le altre funzionalità. Le sezioni [Modalità](https://greph.inline0.dev/it/docs/modes/text), [Indicizzazione](https://greph.inline0.dev/it/docs/indexed/text) e [Compatibilità](https://greph.inline0.dev/it/docs/compatibility/rg) approfondiscono flussi di lavoro specifici.