> Upgrade a Laravel 13: guida pratica alla migrazione da Laravel 12

Perche aggiornare a Laravel 13

Laravel 13 non introduce breaking changes sul codice applicativo: l'upgrade e pensato per essere indolore. Ma restare su Laravel 12 significa rinunciare a PHP Attributes, AI SDK, JSON:API nativo, Queue Routing e Passkey Authentication. Inoltre, Laravel 12 ricevera bug fix solo fino ad agosto 2026 e security fix fino a febbraio 2027.

Aggiornare ora significa avere piu tempo per adottare le novita senza pressione, con il vantaggio di essere gia sulla versione corrente quando usciranno eventuali minor release con fix e miglioramenti. Per i progetti in fase di sviluppo attivo, l'upgrade anticipato e quasi sempre la scelta migliore.

Requisiti preliminari: cosa verificare prima dell'upgrade

Prima di toccare il composer.json, ci sono alcune verifiche essenziali:

PHP 8.3 obbligatorio

Laravel 13 richiede PHP 8.3 come versione minima. Se il server di produzione e ancora su PHP 8.2, bisogna aggiornare prima PHP. Per chi usa servizi managed come Laravel Forge, Ploi o Laravel Cloud, l'aggiornamento di PHP e tipicamente un'operazione rapida. Per server gestiti manualmente, pianificare l'upgrade PHP con anticipo.

Compatibilita dei pacchetti di terze parti

Verificare che tutti i pacchetti nel composer.json supportino Laravel 13. La maggior parte dei pacchetti popolari — Spatie, Laravel Debugbar, Livewire, Filament — rilascia il supporto entro pochi giorni dalla release. Per pacchetti meno mantenuti, controllare le issue su GitHub o valutare alternative.

Un metodo pratico: eseguire composer update --dry-run dopo aver aggiornato il vincolo. Composer mostra i conflitti senza applicare modifiche, permettendo di identificare i pacchetti problematici.

Copertura dei test

Avere una test suite che copre i flussi critici dell'applicazione e il modo migliore per verificare che l'upgrade non abbia introdotto regressioni. Se il progetto non ha test, l'upgrade e comunque sicuro — zero breaking changes lo garantisce — ma e il momento ideale per iniziare a scriverne, almeno per i percorsi principali.

Checklist di migrazione passo per passo

Ecco la procedura completa, testata su diversi progetti in produzione:

• Step 1: Verificare che l'hosting supporti PHP 8.3 o superiore
• Step 2: Creare un branch dedicato per l'upgrade: git checkout -b upgrade/laravel-13
• Step 3: Aggiornare il vincolo in composer.json: "laravel/framework": "^13.0"
• Step 4: Eseguire composer update e risolvere eventuali conflitti di dipendenze
• Step 5: Controllare il file UPGRADE.md nella repository di Laravel per eventuali note specifiche sulla versione
• Step 6: Eseguire la test suite completa con php artisan test
• Step 7: Testare manualmente i flussi critici in locale
• Step 8: Deploy in staging e test completo
• Step 9: Deploy in produzione con monitoring attivo

Problemi comuni durante l'upgrade e come risolverli

Conflitti di dipendenze con Composer

Il problema piu frequente sono pacchetti che dichiarano "illuminate/*": "^12.0" senza includere ^13.0. La soluzione: verificare se esiste una versione aggiornata del pacchetto. Se non esiste, contattare il maintainer o valutare un fork temporaneo.

Deprecation warnings

Alcuni metodi deprecati in Laravel 12 potrebbero essere rimossi in Laravel 13. Controllare i log per DeprecationWarning dopo l'upgrade. Se il progetto usa ignition, le deprecation vengono mostrate nell'interfaccia di errore con indicazione del file e della riga.

Test che falliscono per motivi non legati all'upgrade

A volte, test fragili falliscono per coincidenza temporale (date, timezone) o per dipendenze esterne (API di terze parti, servizi mock scaduti). Prima di attribuire il fallimento all'upgrade, eseguire i test anche sul branch main per confrontare i risultati.

Dopo l'upgrade: adottare le novita in modo incrementale

Una volta su Laravel 13, puoi adottare le novita in modo incrementale senza riscrivere tutto:

• PHP Attributes: iniziare a usarli sui modelli nuovi. Convertire quelli esistenti quando li si modifica per altri motivi.
• AI SDK: integrarlo dove serve, tipicamente in feature nuove. Non forzare l'AI dove non aggiunge valore.
• JSON:API: adottarlo per le API pubbliche nuove. Migrare le API esistenti solo se c'e un motivo concreto.
• Queue Routing: iniziare centralizzando i job nuovi. Migrare quelli esistenti gradualmente.
• Passkey: attivare per le aree che gestiscono dati sensibili. Offrire come opzione, non come obbligo.

Non c'e fretta di riscrivere tutto — il vecchio codice continua a funzionare esattamente come prima. L'approccio incrementale riduce il rischio e distribuisce il lavoro nel tempo.

Timeline di supporto: quando aggiornare

Per pianificare l'upgrade in modo informato, ecco le date chiave:

• Laravel 12: bug fix fino ad agosto 2026, security fix fino a febbraio 2027
• Laravel 13: bug fix fino a settembre 2027, security fix fino a marzo 2028
• Laravel 14: atteso per febbraio 2027 (seguendo il ciclo annuale)

Per progetti in sviluppo attivo, aggiornare entro i primi 2-3 mesi dalla release e la finestra ideale: i pacchetti di terze parti hanno avuto tempo per aggiornarsi e la community ha identificato eventuali problemi.

Consigli per freelance: gestire l'upgrade con i clienti

Come sviluppatore freelance PHP, l'upgrade del framework e un'operazione da proporre proattivamente ai clienti. Alcuni consigli pratici:

• Includere l'upgrade nel piano di manutenzione annuale, con effort stimato e benefici concreti
• Fare l'upgrade in un branch dedicato con PR, cosi il cliente vede le modifiche e approva
• Documentare brevemente le novita rilevanti per il progetto specifico del cliente
• Proporre l'adozione delle novita come evoluzione futura, non come requisito immediato

Un upgrade ben gestito rafforza la fiducia del cliente e dimostra competenza proattiva. Un upgrade trascurato porta a debito tecnico che prima o poi qualcuno dovra pagare.