Vai al contenuto principale

Introduzione

Laravel 10 è stato rilasciato il 14 febbraio 2023. Questa guida illustra la procedura di aggiornamento da Laravel 9.x a 10.x.
Il tempo stimato per l’aggiornamento è di circa 10 minuti. L’impatto dei breaking change sull’app dipende però da dimensione e funzionalità in uso.

Aggiornamento automatico con Laravel Shift

Puoi automatizzare l’aggiornamento con Laravel Shift. Shift aggiorna in automatico dipendenze e file di configurazione dell’applicazione.

Cambiamenti per livello di impatto

Impatto: Alto

  • Aggiornamento delle dipendenze
  • Aggiornamento di minimum-stability

Impatto: Medio

  • Modifica delle espressioni database
  • Rimozione della proprietà $dates dei modelli
  • Monolog 3
  • Redis cache tag
  • Modifiche al mocking dei servizi
  • Directory dei language

Impatto: Basso

  • Messaggi delle validation rule via closure
  • Metodo after di FormRequest
  • Public path binding
  • Costruttore di QueryException
  • Valore di ritorno del rate limiter
  • Rimozione di Redirect::home
  • Rimozione di Bus::dispatchNow
  • Metodo registerPolicies
  • Colonna ULID

Procedura di aggiornamento

Aggiornamento delle dipendenze

Impatto: Alto Aggiorna in composer.json le seguenti dipendenze.
{
  "require": {
    "laravel/framework": "^10.0",
    "laravel/sanctum": "^3.2",
    "doctrine/dbal": "^3.0",
    "spatie/laravel-ignition": "^2.0"
  }
}
Se usi dei pacchetti, aggiornali di conseguenza.
{
  "require": {
    "laravel/passport": "^11.0",
    "laravel/ui": "^4.0"
  }
}
Se usi PHPUnit 10, aggiorna anche:
{
  "require-dev": {
    "nunomaduro/collision": "^7.0",
    "phpunit/phpunit": "^10.0"
  }
}
Se usi PHPUnit 10, rimuovi l’attributo processUncoveredFiles dalla sezione <coverage> in phpunit.xml.
Dopo l’aggiornamento, installa le dipendenze con il comando seguente.
composer update
Per l’aggiornamento di Sanctum da 2.x a 3.x, consulta anche la guida di aggiornamento di Sanctum 3.x.

Aggiornamento di minimum-stability

Impatto: Alto Aggiorna minimum-stability in composer.json a stable. Poiché il valore predefinito è stable, puoi anche rimuovere questa impostazione.
"minimum-stability": "stable"

Requisiti versione PHP

Impatto: Alto Laravel 10 richiede PHP 8.1.0 o superiore e Composer 2.2.0 o superiore.

Modifiche non retrocompatibili (Breaking Changes)

Applicazione

Public path binding

Impatto: Basso Se stai personalizzando il public path bindando path.public al container, passa a usare il metodo usePublicPath di Illuminate\Foundation\Application.
app()->usePublicPath(__DIR__.'/public');

Autorizzazione

Metodo registerPolicies

Impatto: Basso Il metodo registerPolicies di AuthServiceProvider viene ora invocato automaticamente dal framework. Puoi rimuovere la chiamata a questo metodo dal boot.

Cache

Redis cache tag

Impatto: Medio Cache::tags() è raccomandato solo per applicazioni che usano Memcached. Se usi Redis come driver di cache, valuta la migrazione a Memcached.

Database

Modifica delle espressioni database

Impatto: Medio Le espressioni database generate da DB::raw sono state riscritte. Per ottenere il valore string grezzo di un’espressione devi usare il metodo getValue(Grammar $grammar). Il cast a (string) non è più utilizzabile.
use Illuminate\Support\Facades\DB;

$expression = DB::raw('select 1');

// Prima
$string = (string) $expression;

// Dopo
$string = $expression->getValue(DB::connection()->getQueryGrammar());
Solitamente non impatta le app degli utenti finali, ma se stai castando espressioni database a stringa, aggiorna.

Costruttore di QueryException

Impatto: Molto basso Al costruttore di Illuminate\Database\QueryException è stato aggiunto come primo argomento il nome della connessione come stringa. Se lanci manualmente questa eccezione, aggiorna il codice.

Colonna ULID

Impatto: Basso Nelle migration, chiamando ulid senza argomenti il nome della colonna sarà ulid. Nelle release precedenti, chiamandolo senza argomenti veniva creata per errore una colonna chiamata uuid.
// Il nome della colonna sarà "ulid"
$table->ulid();

// Per specificare esplicitamente il nome della colonna
$table->ulid('ulid');

Eloquent

Proprietà $dates dei modelli

Impatto: Medio La proprietà deprecata $dates dei modelli Eloquent è stata rimossa. Usa la proprietà $casts.
// Prima
protected $dates = ['deployed_at'];

// Dopo
protected $casts = [
    'deployed_at' => 'datetime',
];

Localizzazione

Directory dei language

Impatto: Nullo Non impatta le app esistenti, ma lo scheletro di una nuova app Laravel non include più di default la directory lang. Se ti serve, puoi pubblicarla con un comando Artisan.
php artisan lang:publish

Logging

Monolog 3

Impatto: Medio La dipendenza Monolog di Laravel è stata aggiornata a Monolog 3.x. Se usi Monolog direttamente nell’app, controlla la guida di aggiornamento di Monolog. Se usi servizi di logging di terze parti come BugSnag o Rollbar, potrebbe essere necessario aggiornare a versioni che supportino Monolog 3.x e Laravel 10.x.
Le modifiche di Monolog 3.x sono elencate nella guida di aggiornamento di Monolog 3.x.

Code

Rimozione di Bus::dispatchNow

Impatto: Basso I metodi deprecati Bus::dispatchNow e dispatch_now sono stati rimossi. Usa Bus::dispatchSync e dispatch_sync.
// Prima
Bus::dispatchNow(new MyJob());
dispatch_now(new MyJob());

// Dopo
Bus::dispatchSync(new MyJob());
dispatch_sync(new MyJob());

Routing

Alias dei middleware

Impatto: Opzionale Nelle nuove app Laravel la proprietà $routeMiddleware della classe App\Http\Kernel è stata rinominata in $middlewareAliases. L’applicazione ad app esistenti è opzionale.

Valore di ritorno del rate limiter

Impatto: Basso Chiamando il metodo RateLimiter::attempt, il valore restituito dalla closure fornita viene ora restituito così com’è. Se non restituisci nulla o restituisci null, viene restituito true.
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Rimozione di Redirect::home

Impatto: Molto basso Il metodo deprecato Redirect::home è stato rimosso. Passa a un redirect esplicito verso una named route.
// Prima
return Redirect::home();

// Dopo
return Redirect::route('home');

Test

Mocking dei servizi

Impatto: Medio Il trait deprecato MocksApplicationServices è stato rimosso dal framework. Questo trait forniva metodi di test come expectsEvents, expectsJobs e expectsNotifications. Se li usi, migra rispettivamente a Event::fake, Bus::fake e Notification::fake.
// Prima
$this->expectsEvents(OrderShipped::class);

// Dopo
Event::fake();
// ... codice di test ...
Event::assertDispatched(OrderShipped::class);

Validazione

Messaggi delle validation rule via closure

Impatto: Molto basso Con le regole di validazione personalizzate basate su closure, se chiami la callback $fail più volte, i messaggi non vengono più sovrascritti ma aggiunti a un array. Inoltre, la callback $fail restituisce ora un oggetto. Se hai un type hint sul valore di ritorno della closure di validazione, va aggiornato.
public function rules()
{
    return [
        'name' => [
            function ($attribute, $value, $fail) {
                $fail('validation.translation.key')->translate();
            },
        ],
    ];
}

Metodo after di FormRequest

Impatto: Molto basso Il metodo after all’interno delle form request è stato riservato da Laravel. Se hai definito un metodo after in una form request, rinominalo o modificalo per usare la nuova funzionalità “after validation”.

Conclusioni

Laravel 10 è composto da modifiche relativamente piccole e l’aggiornamento si può completare in breve tempo.
ModificaImpattoAzione
Aggiornamento dipendenze in composer.jsonAltoPassa a laravel/framework ^10.0
PHP 8.1 / Composer 2.2 richiestiAltoControlla e aggiorna le versioni
Modifica espressioni databaseMedioSostituisci il cast (string) con getValue()
Rimozione $dates dei modelliMedioMigra a $casts
Monolog 3MedioSe lo usi direttamente controlla la guida di aggiornamento
Redis cache tagMedioValuta la migrazione a Memcached
Rimozione MocksApplicationServicesMedioMigra a Event::fake, ecc.
Rimozione Bus::dispatchNowBassoPassa a Bus::dispatchSync
Nome colonna ULIDBassoVerifica le chiamate a ulid() nelle migration
Rimozione Redirect::homeMolto bassoPassa a Redirect::route('home')

Riferimenti

Ultima modifica il 13 luglio 2026