> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# PHP AST

> Nozioni di base sull'AST (Abstract Syntax Tree) di PHP, il ruolo dell'AST interno di PHP e pattern pratici di analisi e trasformazione del codice con nikic/PHP-Parser.

## Cos'è l'AST di PHP

L'AST (Abstract Syntax Tree — albero sintattico astratto) è una struttura ad albero che scompone il codice sorgente in una "struttura significativa".

Quando crei tool di generazione di codice, tool di analisi statica o strumenti di refactoring automatico, l'AST è quasi sempre la base indispensabile. Trasformazioni che con la semplice sostituzione di stringhe risulterebbero fragili, con l'AST puoi gestirle in sicurezza a livello di unità sintattiche come "function call", "class declaration" o "statement `use`".

```mermaid theme={null}
graph TD
    A["<?php<br>echo add(1, 2);"] --> B["Stmt\\Expression"]
    B --> C["Expr\\FuncCall: add"]
    C --> D["Arg: 1"]
    C --> E["Arg: 2"]
```

## L'AST interno di PHP

Da PHP 7 in poi, la Zend Engine non converte direttamente il codice PHP in opcode: prima lo trasforma in un AST interno e poi lo compila.

* Anche una riga di codice eseguita con `php -r` passa internamente per la stessa pipeline di compilazione
* OPcache mette in cache l'opcode finale generato per riutilizzarlo
* Nello sviluppo di applicazioni standard, quasi mai avrai occasione di manipolare direttamente questo AST interno

In altre parole, quando pensi "voglio modificare il codice usando l'AST", nella pratica non usi l'AST interno del runtime PHP ma una libreria AST utilizzabile in userland.

## Il pacchetto nikic/PHP-Parser

[nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) è la libreria standard per analizzare, attraversare e rigenerare codice PHP come AST. Il README e la documentazione ufficiale illustrano tre passaggi fondamentali.

### Installazione

```bash theme={null}
composer require nikic/php-parser
```

### Esempio base di parsing (dal codice all'AST)

```php theme={null}
<?php

use PhpParser\Error;
use PhpParser\ParserFactory;

$code = <<<'CODE'
<?php
function greet(string $name): void {
    echo "Hello, {$name}";
}
CODE;

$parser = (new ParserFactory())->createForNewestSupportedVersion();

try {
    $ast = $parser->parse($code);
} catch (Error $error) {
    echo "Parse error: {$error->getMessage()}\n";
    return;
}
```

### Attraversare e modificare l'AST con il pattern NodeVisitor

```php theme={null}
<?php

use PhpParser\Node;
use PhpParser\NodeTraverser;
use PhpParser\NodeVisitorAbstract;

$traverser = new NodeTraverser();

$traverser->addVisitor(new class extends NodeVisitorAbstract {
    public function leaveNode(Node $node)
    {
        if ($node instanceof Node\Scalar\Int_) {
            return new Node\Scalar\String_((string) $node->value);
        }
    }
});

$modifiedAst = $traverser->traverse($ast);
```

Estendendo `NodeVisitorAbstract` puoi implementare solo gli hook necessari (`enterNode` / `leaveNode`). Nelle trasformazioni complesse è utile raccogliere informazioni in `enterNode` e sostituire in `leaveNode`.

### Rigenerare il codice con il Pretty Printer

```php theme={null}
<?php

use PhpParser\PrettyPrinter;

$prettyPrinter = new PrettyPrinter\Standard();
$newCode = $prettyPrinter->prettyPrintFile($modifiedAst);

echo $newCode;
```

Con questo flusso l'oggetto della trasformazione non è "codice come stringa" ma "codice come albero sintattico".

## Esempio d'uso in Laravel/Chisel

[laravel/chisel](/it/blog/chisel-introduction) è una libreria che post-elabora gli starter kit per rimuoverne parti. In `composer.json` include la 5.x di `nikic/php-parser` come dipendenza.

In `Laravel\Chisel\Ast\Source`, Chisel esegue le modifiche dell'AST con questi passaggi.

1. Parsing del codice con `ParserFactory::createForNewestSupportedVersion()`
2. Aggiunta di più Visitor (come `RemoveImportVisitor`) a un `NodeTraverser` per le trasformazioni
3. Riscrittura preservando la formattazione originale con `printFormatPreserving()` di `PhpParser\PrettyPrinter\Standard`

Questo design permette di eliminare in sicurezza `use`, trait e interfacce a livello di sintassi, invece che con sostituzioni testuali.

## Casi d'uso

L'AST facilita sviluppi come questi.

* CLI per la generazione di codice (modifica per unità sintattiche dopo aver creato uno scaffold)
* Tool di analisi statica (rilevamento di sintassi specifiche o violazioni di regole)
* Refactoring automatico (semi-automatizzazione di migrazioni API o rinomine)
* Post-processing di template di progetto (rimozione o sostituzione di funzionalità, come in Chisel)

## Riepilogo

L'AST di PHP non è una funzionalità che usi tutti i giorni nello sviluppo di applicazioni Laravel.

Tuttavia, se ti occupi di tool o di sviluppo di pacchetti, l'AST diventa una base potente per modifiche al codice "difficili da rompere e riproducibili". Inizia sperimentando i tre elementi di `nikic/php-parser` — Parser, Visitor, Pretty Printer — in una piccola CLI.


## Related topics

- [Laravel Chisel — libreria di script post-installazione per starter kit](/it/blog/chisel-introduction.md)
- [PHP FFI](/it/advanced/ffi.md)
- [Attributi PHP](/it/advanced/php-attributes.md)
- [VOICEVOX Core for PHP](/it/packages/voicevox-core-php/index.md)
- [PHP Reflection API](/it/advanced/php-reflection.md)