Questa pagina è una guida complementare a Sviluppo di pacchetti Laravel, Testare pacchetti Laravel con Orchestra Testbench e Gestire la compatibilità tra versioni dei pacchetti. Aggiungere l’analisi statica a implementazione, test e strategia di versioning rende il pacchetto più stabile a lungo termine.
Cos’è l’analisi statica
L’analisi statica rileva incongruenze di tipo e bug potenziali senza eseguire il codice. In un pacchetto Laravel — service container, facade, Eloquent — ci sono molti meccanismi dinamici: verifiche a runtime da sole rischiano di lasciare passare problemi. L’analisi statica li intercetta in anticipo. Introducendola ottieni in particolare questi vantaggi.- Migliore type-safety — rilevi argomenti o valori di ritorno sbagliati già prima della review
- Bug scoperti prima — trovi chiamate a metodi inesistenti o nullable dimenticati prima dei test
- Autocompletamento IDE migliore — sistemando PHPDoc e generics l’accuratezza dell’IDE aumenta
- Manutenzione a lungo termine più stabile — durante gli upgrade Laravel/PHP individui prima cosa si rompe
Setup di PHPStan
Prima predisponi la base di analisi con solo PHPStan. PHPStan 2.x gestiscemixed e nullable in modo più rigido: è una buona occasione per sistemare le API pubbliche del pacchetto.
Setup di Larastan
Nei pacchetti Laravel, il solo PHPStan non capisce del tutto meccanismi Laravel-specifici come risoluzione dal container, facade e relazioni Eloquent. Perciò affianchi Larastan, l’estensione Laravel di PHPStan.Aggiungere Larastan
Il nome attuale del pacchetto è
larastan/larastan. Negli articoli vecchi potresti trovare nunomaduro/larastan.Per lo sviluppo di pacchetti installa anche Testbench
Larastan avvia il container Laravel per risolvere i tipi. Nell’analisi standalone di un pacchetto Laravel a volte serve
orchestra/testbench.Configurazione di phpstan.neon
phpstan.neon è il file centrale che raccoglie livello di analisi, path da analizzare, path da escludere e regole di eccezione. Per un pacchetto Laravel è più realistico partire da un setup che puoi far salire nel tempo, piuttosto che puntare al 100% da subito.
Esempio di phpstan.neon:
Come scegliere il livello 0–9
PHPStan si introduce in modo graduale. Parti dal livello che la codebase attuale riesce a superare e alza man mano che sistemi le cose.| Livello | Fase indicata |
|---|---|
| 0–3 | Vuoi ridurre chiamate a classi, funzioni o metodi sconosciuti |
| 4–6 | Vuoi sistemare argomenti, valori di ritorno e proprietà dell’API pubblica |
| 7–9 | Fase di manutenzione a lungo termine: gestisci nullable, union, mixed in modo rigido |
paths
In paths indichi esplicitamente le directory da analizzare. Includere non solo src ma anche tests (dove i tipi tendono a rilassarsi) è efficace.
excludePaths
Escludi solo i luoghi in cui l’analisi statica ha poco valore: file generati, cache, Workbench di verifica. Escludere troppo nasconde gli errori che invece vorresti vedere.
ignoreErrors
ignoreErrors è l’ultima risorsa. Restringi il messaggio con una regex e limita l’impatto con path. Così quando Laravel o Larastan miglioreranno, sarà più facile ripristinare.
Annotazioni di tipo frequenti
L’accuratezza di PHPStan e Larastan cambia molto in base a come scrivi il PHPDoc. Nei pacchetti Laravel vale la pena sistemare in particolare@param, @return, @var e i generics (@template).
@param class-string<TModel>— indica che la stringa non è arbitraria ma il nome di una classe Model@return TModel|null— comunica chefind()restituisce un tipo Model concreto@var Collection<int, TModel>— esplicita i tipi key/value della collection@template TModel of Model— descrive un generic repository riutilizzabile
Punti specifici di Laravel
La “magic” comoda di Laravel non è visibile all’analisi statica così com’è. Devi aggiungere informazioni di tipo dal lato pacchetto per portarle nella forma che l’analizzatore comprende.Facade
Nei facade custom, integrando i metodi richiamati dagli utenti con PHPDoc, ottieni benefici sia per IDE sia per analisi statica.Magic method
Le API che si basano su__call() o su Macroable sono comode, ma è facile che il tipo salti. Se sono API pubbliche, aggiungere wrapper con argomenti e valori di ritorno chiari è più sicuro.
Tipizzazione dei modelli Eloquent
Per relazioni e proprietà dinamiche di Eloquent, la combinazione di@property e generics sulle relation è efficace.
Esecuzione automatica in CI
Esegui l’analisi statica anche in CI, non solo in locale. In particolare, se il pacchetto supporta più versioni di Laravel, usare la stessa logica della test matrix di Gestire la compatibilità tra versioni dei pacchetti permette di controllare in parallelo compatibilità e type-safety. Esempio di.github/workflows/static-analysis.yml:
Falsi positivi frequenti e come gestirli
Davanti a un warning di analisi statica chiediti prima “manca qualche informazione di tipo?”. Spesso un falso positivo è in realtà un PHPDoc mancante.@phpstan-ignore-next-line
Utile come workaround temporaneo, ma limitalo alle righe di cui puoi spiegare tu stesso il motivo.
ignoreErrors
Da considerare solo quando lo stesso errore appare in più punti. Restringi sempre il path e non usare regex generici che nascondono tutto.
Ordine di priorità
- Aggiungi PHPDoc
- Esplicita i tipi di ritorno di facade e relation
- Sostituisci
mixedcon tipi concreti - Ignora solo i falsi positivi che sai spiegare
Pagine correlate
Sviluppo di pacchetti Laravel
Rivedi le basi di implementazione di un pacchetto, service provider e risorse pubblicate incluse.
Testare pacchetti Laravel con Orchestra Testbench
Rivedi la struttura di test per pacchetti da combinare con l’analisi statica.
Gestire la compatibilità tra versioni dei pacchetti
Rivedi la tabella di compatibilità Laravel/PHP e la strategia matrix di GitHub Actions.