# Guida introduttiva

## Installazione

Installa Greph tramite Composer:

```bash
composer require greph/greph
```

Questo installa la libreria e quattro eseguibili in `vendor/bin/`:

- `greph`: ricerca testuale nativa, ricerca AST e riscrittura AST
- `greph-index`: indice testuale precaricato, indice dei fatti AST e ricerca AST memorizzata nella cache
- `rg`: wrapper di compatibilità in stile ripgrep
- `sg`: wrapper di compatibilità in stile ast-grep

Questi eseguibili funzionano dalla `vendor/bin/` del progetto, poiché Greph 0.2.3. Le versioni precedenti trovavano l'autoloader di Composer solo all'interno di un clone del repository Greph, quindi è richiesta almeno quella versione:

```bash
composer require greph/greph:^0.2.3
```

## Requisiti

- **PHP 8.2+** per classi readonly, enum, sintassi callable di prima classe e promozione dei parametri nel costruttore
- **ext-json** per l'output JSON e i payload degli indici su disco
- **ext-ctype** per analizzare pattern e opzioni
- **ext-tokenizer** per PHP-Parser e i prefiltri AST
- **ext-zlib** per l'archivio AST nella cache (`greph-index ast-cache`)
- **nikic/php-parser** (installato automaticamente come dipendenza di Composer)

`ext-json`, `ext-ctype` e `ext-tokenizer` sono abilitati in quasi tutte le build di PHP. `composer.json` dichiara al momento solo `ext-json` ([#5](https://github.com/inline0/greph/issues/5)), quindi Composer non avvisa se ne manca uno degli altri.

Facoltativo:

- **ext-pcntl** per le scansioni parallele. Greph passa senza problemi all'esecuzione a processo singolo se manca.
- Binari esterni di `rg`, `grep` e `sg` per i confronti dei benchmark. Non sono mai richiesti in fase di esecuzione.

La ricerca, la riscrittura e l'indicizzazione non chiamano mai `proc_open()` o `shell_exec()`; solo le scansioni parallele creano processi figli e passano a un singolo processo se manca `pcntl_fork()`. Consultate [Host con processi limitati](https://greph.inline0.dev/it/docs/advanced/process-restricted-hosts) per gli host che disabilitano `proc_open()`, `shell_exec()` o `pcntl_fork()`.

## La prima ricerca testuale

La modalità predefinita di Greph è la ricerca testuale compatibile con grep:

```bash
vendor/bin/greph -F "function" src
```

L'output usa il formato canonico `file:line:content` previsto da grep, ripgrep e dalla maggior parte delle integrazioni degli editor.

```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(
```

Aggiungete `-i` per ignorare la distinzione tra maiuscole e minuscole, `-w` per la corrispondenza di parole intere, `-c` per i conteggi, `-l` per i soli percorsi dei file, `-C 2` per due righe di contesto e così via. L'elenco completo si trova nel [riferimentoCLI](https://greph.inline0.dev/it/docs/cli).

## La prima ricerca AST

Passate `-p` e un pattern in formato PHP per passare alla ricerca strutturale:

```bash
vendor/bin/greph -p 'new $CLASS()' src
```

`$CLASS` è una metavariabile che acquisisce qualsiasi nome di classe. Il pattern `new $CLASS()` corrisponde a ogni espressione `new` senza argomenti, indipendentemente dalla classe, dalla formattazione o dai commenti. Usate `new $CLASS($$$ARGS)` per trovare chiamate con qualsiasi argomento.

Ogni corrispondenza AST viene stampata indicando il file, la riga iniziale e il codice corrispondente:

```text
src/Greph.php:43:new FileWalker()
src/Greph.php:52:new TextSearchOptions()
src/Greph.php:54:new TextSearcher()
```

Altri pattern utili:

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

Consultate [Modalità / Ricerca AST](https://greph.inline0.dev/it/docs/modes/ast) per la sintassi completa dei pattern.

## La prima riscrittura

Aggiungete `-r` per trasformare la ricerca AST in una riscrittura:

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

Le riscritture preservano la formattazione al di fuori della corrispondenza: viene sostituito solo il nodo corrispondente, mentre spazi, indentazione e commenti circostanti restano intatti. Il nodo corrispondente viene ricreato dal template, quindi il suo layout viene normalizzato e un commento al suo interno può andare perso. Per i dettagli, consultate [Modalità / Riscrittura](https://greph.inline0.dev/it/docs/modes/rewrite).

## PHP API

La facciata statica `Greph\Greph` espone le stesse operazioni di 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";
}
```

La superficie completa è descritta in [API](https://greph.inline0.dev/it/docs/api).

## Ricerca indicizzata

I carichi di lavoro ripetuti traggono vantaggio dagli indici precaricati. Create l'indice una volta, poi eseguite molte query:

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

Per impostazione predefinita, gli indici si trovano in `.greph-index`, `.greph-ast-index` e `.greph-ast-cache` nella radice del progetto.

Per alberi che cambiano spesso, scegliete un profilo del ciclo di vita invece di trattare tutti gli indici precaricati allo stesso modo:

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

Lo schema comune è:

- mantenere una base stabile come `static`
- mantenere le sovrapposizioni che cambiano spesso come `opportunistic-refresh`
- esaminare il comportamento dei dati obsoleti con `stats --dry-refresh`

### Ricerca precaricata su più indici

Potete cercare in più indici precaricati con un solo comando:

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

### Gruppi di indici con nome

Se ripetete spesso questa operazione, inserite la struttura in `.greph-index-set.json` e usate i sottocomandi dei gruppi invece di ripetere i flag:

```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)' .
```

### Traccia del pianificatore

Per vedere come la ricerca precaricata restringe l'insieme dei candidati, aggiungete `--trace-plan`:

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

Consultate [Indicizzato / Testo](https://greph.inline0.dev/it/docs/indexed/text) e [Indicizzato / AST](https://greph.inline0.dev/it/docs/indexed/ast) per il flusso di lavoro precaricato completo.

## Wrapper di compatibilità

Se avete strumenti o agenti che usano già ripgrep o ast-grep, aggiungete i wrapper:

```bash
vendor/bin/rg --json -F "function" src
vendor/bin/sg --pattern 'new $CLASS()' src --lang php
```

Entrambi i wrapper riutilizzano lo stesso motore e sono verificati tramite test rispetto ai binari upstream. Le funzionalità verificate sono documentate in [Compatibilità / rg](https://greph.inline0.dev/it/docs/compatibility/rg) e [Compatibilità / sg](https://greph.inline0.dev/it/docs/compatibility/sg) e riprodotte nella [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix) generata.

## Configurazione

Greph riconosce due convenzioni su disco:

- `.gitignore`: rispettato per impostazione predefinita. Passate `--no-ignore` per disabilitarlo.
- `.grephignore`: stessa sintassi di `.gitignore`, applicata in aggiunta. Utile per esclusioni specifiche dello strumento che non volete includere nel controllo di versione.

Le directory predefinite degli indici sono `.greph-index`, `.greph-ast-index` e `.greph-ast-cache` nella radice scelta. Sovrascrivetele con `--index-dir` in qualsiasi sottocomando `greph-index` oppure usate `.greph-index-set.json` per strutture ripetibili con più indici.