Analisi statica con PHPStan

Settimo articolo della serie sui fondamenti dello sviluppo di plugin WordPress. Nell’articolo precedente abbiamo configurato PHPCS per far rispettare gli standard di codifica. Ora aggiungiamo un secondo livello di controllo: l’analisi statica con PHPStan.

PHPCS verifica come appare il tuo codice. PHPStan verifica se il tuo codice è corretto. È uno strumento di analisi statica: legge i tuoi file PHP e ragiona su tipi, logica e flusso del programma — il tutto senza mai eseguire il codice.

Alla fine di questo articolo avrai PHPStan configurato per il tuo plugin WordPress, funzionante in locale e nella pipeline CI.

Cos’è PHPStan

PHPStan analizza il tuo codice sorgente e trova bug che sfuggono facilmente a occhio nudo: argomenti del tipo sbagliato passati a una funzione, metodi chiamati su oggetti che potrebbero essere null, codice irraggiungibile dopo un return, condizioni che non possono mai essere vere.

Lo strumento lavora su un sistema a livelli, da 0 a 9. Il livello 0 esegue controlli di base, ogni livello successivo aggiunge controlli più rigorosi. Non servono test, non serve eseguire il codice — PHPStan lavora esclusivamente sui file sorgente.

La differenza chiave rispetto a PHPCS: PHPCS si occupa di stile e convenzioni, PHPStan si occupa di correttezza e logica. Sono complementari, non alternativi.

Installazione via Composer

Installa PHPStan e l’estensione WordPress come dipendenze di sviluppo:

composer require --dev phpstan/phpstan \
    szepeviktor/phpstan-wordpress

Il pacchetto phpstan/phpstan è lo strumento stesso. Il pacchetto szepeviktor/phpstan-wordpress è fondamentale: fornisce a PHPStan le informazioni sui tipi di tutte le funzioni WordPress core — add_action, get_post, wp_query e così via. Senza questa estensione, PHPStan non conosce WordPress e segnalerà errori su praticamente ogni riga che usa funzioni del core.

Configurazione con phpstan.neon.dist

PHPStan usa il formato NEON per la configurazione — simile a YAML, con qualche differenza sintattica. Come per PHPCS, la convenzione .dist indica un file committato nel repository, sovrascrivibile localmente con phpstan.neon.

Crea phpstan.neon.dist nella root del plugin:

includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon

parameters:
    level: 0
    paths:
        - src/
        - my-awesome-plugin.php
    excludePaths:
        - vendor/
        - tests/

Il campo includes carica l’estensione WordPress — senza questa riga PHPStan non riconosce le funzioni del core. In paths specifichi le directory e i file da analizzare. In excludePaths escludi ciò che non va analizzato.

Il punto più importante è level. Ecco una panoramica sintetica: il livello 0 verifica che le classi e le funzioni chiamate esistano, il livello 3 aggiunge i controlli sui tipi di ritorno, il livello 5 trova codice morto, il livello 8 vieta i tipi mixed, e il livello 9 è il più rigoroso in assoluto.

Il consiglio per iniziare: parti dal livello 0. Assicurati che passi senza errori, poi aumenta gradualmente. Saltare direttamente al livello 6 su un progetto esistente produce centinaia di errori e scoraggia chiunque.

Eseguire PHPStan

Lancia l’analisi:

vendor/bin/phpstan analyse

PHPStan legge automaticamente phpstan.neon.dist e analizza i file configurati. L’output è chiaro: per ogni problema troverai il file, il numero di riga e un messaggio che spiega l’errore.

Se stai aggiungendo PHPStan a un plugin esistente, il concetto di baseline ti sarà utile. Una baseline registra tutti gli errori attuali in un file separato, permettendoti di aumentare il livello senza dover risolvere tutto subito:

vendor/bin/phpstan analyse --generate-baseline

Questo crea un file phpstan-baseline.neon. Includilo nella configurazione:

includes:
    - vendor/szepeviktor/phpstan-wordpress/extension.neon
    - phpstan-baseline.neon

Da questo momento PHPStan ignora gli errori noti e segnala solo quelli nuovi. Puoi affrontare il debito tecnico gradualmente, senza bloccare lo sviluppo.

Aggiungi lo script Composer, seguendo lo stesso pattern degli articoli precedenti:

{
    "scripts": {
        "phpstan": "phpstan analyse"
    }
}

Ora composer run phpstan funziona ovunque — in locale e in CI.

Integrazione in GitHub Actions

Nell’articolo su GitHub Actions avevamo già preparato lo step. Attivarlo è una riga:

      - name: Run static analysis
        run: composer run phpstan

Se usi una baseline, assicurati che il file phpstan-baseline.neon sia committato nel repository — il runner CI ne ha bisogno per sapere quali errori ignorare.

Ora ogni Pull Request passa attraverso due controlli di qualità automatici: PHPCS per lo stile e PHPStan per la correttezza. Due reti di sicurezza complementari che lavorano senza nessun intervento manuale.

Prossimi passi

Con PHPCS e PHPStan hai due strumenti che analizzano il codice da prospettive diverse — convenzioni e correttezza — entrambi automatizzati nella pipeline CI. Questo è già un setup di qualità professionale.

Nel prossimo articolo chiudiamo il cerchio con PHPUnit: test automatizzati che verificano il comportamento effettivo del tuo plugin. Ricordi l’istanza di test di wp-env dall’articolo sull’ambiente locale? È il momento di metterla al lavoro.

Prossimo articolo: Test automatizzati con PHPUnit →