Come analizzare staticamente i progetti PHP con PHPStan

PHPStan è un sistema di analisi statica per progetti PHP. Trova i bug nella tua base di codice ispezionando i file sorgente. Non è necessario eseguire il codice o scrivere manualmente i test per rilevare i problemi!

Il termine “analisi statica” è definito come codice di debug senza eseguirlo effettivamente. Viene utilizzato più spesso con linguaggi interpretati, come PHP, poiché i problemi che rileva tendono a emergere nella fase di compilazione nei linguaggi compilati.

L'analisi statica tende a fornire i risultati migliori quando viene eseguita all'interno una base di codice ben strutturata e fortemente tipizzata. La documentazione di PHPStan consiglia che il “codice orientato agli oggetti moderno” ne trarrà il massimo vantaggio, poiché questi progetti forniscono a PHPStan maggiori informazioni con cui lavorare.

Aggiungere PHPStan al tuo progetto

Per eseguire PHPStan, devi avere PHP 7.1 o successivo. Questo requisito si applica solo alla versione di PHP utilizzata per eseguire PHPStan stesso. Lo strumento è in grado di analizzare i file sorgente destinati a versioni precedenti di PHP.

Si consiglia di utilizzare Composer per aggiungere PHPStan come dipendenza:

il compositore richiede –dev phpstan/phpstan

Il binario PHPStan verrà aggiunto al tuo progetto in vendor/bin/phpstan. Ora puoi usarlo per analizzare la tua base di codice per la prima volta:

vendor/bin/phpstan analizza src

Il comando mostrato sopra eseguirà i test di PHPStan su tutti i file sorgente nella tua directory src. A seconda delle dimensioni della tua base di codice, il completamento potrebbe richiedere alcuni minuti.

< /p>

Vedrai un verde “[OK] Nessun errore” messaggio se tutti i test passano. In caso contrario, verrà visualizzato l'elenco degli errori riscontrati. Segui la guida mostrata per risolvere ogni errore prima di eseguire nuovamente PHPStan.

Tipi e livelli di errore

PHPStan include una pletora di controlli che coprono una vasta gamma di possibili problemi di codebase. Alcuni dei più comuni che incontrerai includono i seguenti:

Digita i problemi di sistema– Assegnazione di un valore non valido a una proprietà digitata o passaggio di parametri digitati in modo errato a un metodo. Ciò include anche problemi di contratto, come una classe che implementa in modo errato un'interfaccia.
Richiamo di funzioni – Passare troppi o non abbastanza parametri quando si chiama una funzione o un metodo (ad es. 3 invece di 4).
Classi, metodi e funzioni sconosciuti – Cercando di utilizzare qualcosa che non esiste all'interno del codebase.
Accesso a variabili non definite/forse non definite– Cercando di utilizzare una variabile che non è definita in un determinato ambito, o quella che potrebbe non avere sempre un valore ma viene utilizzata in un contesto in cui si presume uno.
Controllo del codice morto – Segnalazione di codice inutile, come i confronti booleani che si risolveranno sempre con lo stesso valore e i rami di codice che non verranno mai eseguiti (ad es. il codice che segue un'istruzione return all'interno delle funzioni).

Le regole sono ordinate in 9 diversi “livelli”, etichettati da 0 a 8. Il livello speciale max funge da alias per il livello più alto possibile. Nel tempo, PHPStan può aggiungere ulteriori livelli numerici, quindi l'utilizzo di max garantisce di ottenere sempre i controlli più severi possibili.

Per impostazione predefinita, PHPStan esegue il livello 0. Questo include solo i test più fondamentali. È una buona idea fare in modo che la tua base di codice superi ogni livello individualmente prima di passare a quello successivo. È probabile che i progetti maturi incorrano in un'altra serie di problemi con ogni nuovo livello.

Per cambiare il livello utilizzato da PHPStan, puoi passare il parametro della riga di comando –level:

vendor/bin/phpstan analizza src –level 8

Oltre al built-in controlli, le estensioni PHPStan sono disponibili per aggiungere ancora più funzionalità. Puoi anche scrivere le tue regole da zero. Ciò è utile quando stai deprecando funzionalità che gli sviluppatori non dovrebbero più utilizzare in alcun nuovo codice. Tratteremo la creazione di regole personalizzate in un prossimo articolo.

Configurazione di PHPStan

Al di là della sperimentazione iniziale, l'utilizzo dell'interfaccia a riga di comando di PHPStan può diventare rapidamente noioso. È meglio aggiungere un file di configurazione al tuo progetto che può quindi essere impegnato nel controllo del codice sorgente affinché tutti i tuoi sviluppatori possano utilizzarlo.

PHPStan utilizza il formato del file di configurazione Neon, che ha una sintassi molto simile a YAML. Crea un file phpstan.neon nella directory principale del tuo progetto. Questo file viene caricato automaticamente all'avvio di PHPStan, quindi ora puoi eseguire il comando di analisi senza ulteriori argomenti:

vendor/bin/phpstan analisi

Per sovrascrivere il file di configurazione utilizzato, passare il flag –configuration :

vendor/bin/phpstan analizza –configuration /phpstan-config.neon

Ora devi popolare il tuo file phpstan.neon con del contenuto. Un buon punto di partenza potrebbe essere questo:

parametri: livello: 0 percorsi: – src Annuncio

Questo file di configurazione di base dovrebbe fornire lo stesso output dell'invocazione della riga di comando mostrata in precedenza. Puoi aggiungere ulteriori directory da scansionare come nuove linee nella sezione dei percorsi. Per escludere file e directory, aggiungili a una foglia excludes_analyse all'interno della stessa sezione dei parametri.

Ignora errori

Occasionalmente, PHPStan può far emergere un problema che è inevitabile. Se c'è un problema che non puoi affrontare immediatamente, potresti volerlo ignorare esplicitamente per consentire il superamento dei test.

Ciò è particolarmente importante quando si desidera passare a un altro livello di controlli o si utilizza PHPStan in un ambiente CI in cui un'esecuzione non riuscita interromperà la distribuzione della build. Anche così, non prendere alla leggera questa linea di condotta – dovresti scegliere di ignorare un errore segnalato solo se sei certo che sarà sicuro farlo.

Una volta presa la decisione, aggiungi una nuova sezione ignoreErrors all'interno dei parametri del tuo file di configurazione. Devi definire il messaggio da abbinare, come regex, e i percorsi a cui applicare l'esclusione a:

parametri: level: 0 percorsi: – src ignoreErrors: – messaggio: '/Return type stringa del metodo ExampleClass:: esempio() non è covariante(.*).' percorso: src/ExampleClass.php

Puoi facoltativamente specificare i percorsi come un array di percorsi, sostituendo la chiave del singolo percorso mostrata sopra.

Regole facoltative

< p>La severità di PHPStan può essere regolata da una serie di variabili di configurazione. Questi consentono di affinare i controlli che vengono effettuati, al di fuori del sistema dei livelli sopra descritto. Alcuni di questi sono potenzialmente controversi o è improbabile che si allineino con tutte le guide di stile private, quindi sono disattivati per impostazione predefinita.

Alcune impostazioni che potrebbero valere la pena abilitare includono:

checkAlwaysTrueInstanceof – Utilizza flag di instanceof che verrà sempre valutato come true.
checkAlwaysTrueStrictComparison – Contrassegna quando un'espressione che utilizza === o !== verrà sempre valutata come vera.
checkFunctionNameCase – Assicura che il maiuscolo dei nomi delle funzioni corrisponda alla loro definizione quando viene chiamato in tutta la codebase.
polluteScopeWithLoopInitialAssignments – Quando è impostato su false (è vero per impostazione predefinita), non è possibile accedere alle variabili dichiarate nelle istruzioni del ciclo iniziale (ad es. $i in $for ($i = 1; $i < 10; $i++)) all'esterno blocco di codice del ciclo, evitando il possibile inquinamento dell'ambito padre.
reportStaticMethodSignatures – Impone il controllo completo del tipo per i parametri e i tipi restituiti nei metodi statici quando vengono sovrascritti da una classe figlio.

Annuncio

Dettagli completi su queste impostazioni facoltative – e molti altri – può essere trovato nel riferimento alla configurazione di PHPStan.

Conclusione

Questa è la fine della nostra introduzione a PHPStan. Ti aiuta ad avere fiducia nella tua base di codice ed evidenzia possibili problemi prima che diventino un problema in produzione.

PHPStan è così veloce da configurare che non c'è davvero alcun motivo per non usarlo, specialmente quando si lavora con un moderno codebase fortemente tipizzato. Tuttavia, non farti ingannare nel pensare che possa sostituire il test manuale. PHPStan può vantare un vasto assortimento di controlli ma non è in grado di identificare problemi logici e non comprende le regole di business del tuo progetto. È semplicemente un'altra risorsa nella tua cassetta degli attrezzi quando valuti l'integrità di una codebase, servendo insieme a compagni fidati come test di unità e test di funzionalità end-to-end.