Vai al contenuto principale

Introduzione

Laravel 11 è stato rilasciato a marzo 2024. Questa guida illustra la procedura di aggiornamento da Laravel 10.x a 11.x.
Il tempo stimato necessario all’aggiornamento è di circa 15 minuti. L’impatto dei breaking change sulla tua applicazione varia però in base alle dimensioni e alle funzionalità utilizzate.

Aggiornamento automatico con Laravel Shift

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

Cambiamenti per livello di impatto

Impatto: Alto

  • Aggiornamento delle dipendenze
  • Modifica della struttura dell’applicazione
  • Modifiche ai tipi in virgola mobile
  • Conservazione degli attributi al cambio di colonna
  • Versione minima di SQLite
  • Aggiornamento di Sanctum

Impatto: Medio

  • Carbon 3
  • Rehashing delle password
  • Rate limiting al secondo
  • Pacchetto Spatie Once

Impatto: Basso

  • Rimozione di Doctrine DBAL
  • Metodo casts dei modelli Eloquent
  • Modifiche ai tipi spaziali
  • Contract Enumerable
  • Contract UserProvider
  • Contract Authenticatable

Procedura di aggiornamento

Aggiornamento delle dipendenze

Impatto: Alto Aggiorna in composer.json le seguenti dipendenze.
{
  "require": {
    "laravel/framework": "^11.0",
    "nunomaduro/collision": "^8.1"
  }
}
Se usi dei pacchetti, aggiornali di conseguenza.
{
  "require": {
    "laravel/breeze": "^2.0",
    "laravel/cashier": "^15.0",
    "laravel/dusk": "^8.0",
    "laravel/jetstream": "^5.0",
    "laravel/octane": "^2.3",
    "laravel/passport": "^12.0",
    "laravel/sanctum": "^4.0",
    "laravel/scout": "^10.0",
    "laravel/spark-stripe": "^5.0",
    "laravel/telescope": "^5.0",
    "livewire/livewire": "^3.4",
    "inertiajs/inertia-laravel": "^1.0"
  }
}
Dopo l’aggiornamento, installa le dipendenze con il comando seguente.
composer update
Se usi Cashier Stripe, Passport, Sanctum, Spark Stripe o Telescope, devi pubblicare le migration nell’applicazione.
php artisan vendor:publish --tag=cashier-migrations
php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations
Se usi l’installer di Laravel, aggiornalo di conseguenza.
composer global require laravel/installer:^5.6
Se in passato avevi aggiunto manualmente doctrine/dbal, puoi rimuoverlo. Laravel 11 non dipende più da questo pacchetto.

Requisiti versione PHP

Impatto: Alto Laravel 11 richiede PHP 8.2.0 o superiore. Il client HTTP di Laravel richiede inoltre curl 7.34.0 o superiore.

Modifica della struttura dell’applicazione

Impatto: Alto In Laravel 11 la struttura predefinita dell’applicazione è stata semplificata. Il numero di service provider, middleware e file di configurazione è stato notevolmente ridotto. Detto ciò, quando aggiorni un’app Laravel 10 a Laravel 11, non è raccomandato provare a migrare la struttura dell’applicazione. Laravel 11 è progettato per supportare anche la struttura di app di Laravel 10. Principali modifiche strutturali:
  • In bootstrap/app.php si configurano ora direttamente middleware, exception handler e routing
  • app/Http/Kernel.php è stato dismesso e integrato in bootstrap/app.php
  • Il numero di service provider predefiniti è stato ridotto e vengono gestiti in bootstrap/providers.php
  • Il numero di file nella directory config/ è stato ridotto (se serve puoi pubblicarli con php artisan config:publish)

Modifiche non retrocompatibili (Breaking Changes)

Autenticazione

Rehashing delle password

Impatto: Medio In Laravel 11, se il “work factor” dell’algoritmo di hash è cambiato, in fase di autenticazione la password viene rehashata automaticamente. Se nel modello User il campo password ha un nome diverso da password, specificalo nella proprietà authPasswordName del modello.
class User extends Authenticatable
{
    protected $authPasswordName = 'custom_password_field';
}
Per disabilitare questa funzionalità, aggiungi a config/hashing.php:
'rehash_on_login' => false,

Contract UserProvider

Impatto: Basso Al contract Illuminate\Contracts\Auth\UserProvider è stato aggiunto il metodo rehashPasswordIfRequired. Se hai classi che implementano questa interfaccia, aggiungi il metodo.
public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

Contract Authenticatable

Impatto: Basso Al contract Illuminate\Contracts\Auth\Authenticatable è stato aggiunto il metodo getAuthPasswordName. Se hai classi che implementano questa interfaccia, aggiungi il metodo.
public function getAuthPasswordName()
{
    return 'password';
}

Database

Versione minima di SQLite

Impatto: Alto Se usi SQLite, è richiesto SQLite 3.26.0 o superiore. Nei nuovi progetti Laravel 11 il driver database predefinito è SQLite.

Conservazione degli attributi al cambio di colonna

Impatto: Alto Quando modifichi una colonna, tutti i modificatori che vuoi mantenere dopo la modifica vanno specificati esplicitamente. Gli attributi non indicati vengono rimossi.
// In Laravel 10 unsigned, default e comment venivano mantenuti
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

// In Laravel 11 devi specificare esplicitamente tutti gli attributi
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});
Se non vuoi aggiornare tutte le migration esistenti, effettua uno squash.
php artisan schema:dump

Modifiche ai tipi in virgola mobile

Impatto: Alto I tipi di colonna double e float sono stati unificati su tutti i database.
// double: non servono più argomenti di cifre totali/cifre decimali
$table->double('amount');

// float: solo un argomento opzionale di precisione
$table->float('amount', precision: 53);
I metodi unsignedDecimal, unsignedDouble e unsignedFloat sono stati rimossi. Se vuoi usare comunque l’attributo unsigned, specificalo in chain.
$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();

Metodo casts dei modelli Eloquent

Impatto: Basso Nella classe base dei modelli Eloquent è stato definito il metodo casts. Se in un modello dell’applicazione hai definito una relazione chiamata casts, dovrai rinominarla per evitare il conflitto.

Driver dedicato MariaDB

Impatto: Molto basso Laravel 11 aggiunge un driver database dedicato per MariaDB. Se ti connetti a MariaDB, puoi usare il driver mariadb nella configurazione.
'driver' => 'mariadb',

Modifiche ai tipi spaziali

Impatto: Basso I tipi di colonna spaziali sono stati unificati su tutti i database. Al posto dei metodi come point, lineString e polygon, usa geometry o geography.
$table->geometry('shapes');
$table->geography('coordinates');
Se vuoi specificare esplicitamente il tipo o il sistema di riferimento spaziale, passa subtype e srid.
$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);

Rimozione di Doctrine DBAL

Impatto: Basso Laravel ha eliminato la dipendenza da Doctrine DBAL. Sono state rimosse le seguenti classi e metodi.
  • Schema\Builder::useNativeSchemaOperationsIfPossible()
  • Connection::getDoctrineConnection()
  • Connection::getDoctrineSchemaManager()
  • Connection::registerDoctrineType()
  • DatabaseManager::registerDoctrineType()
  • Classe Schema\Grammars\ChangeColumn
  • Classe Schema\Grammars\RenameColumn
Per l’ispezione del database usa i nuovi metodi nativi come Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys().

Date

Carbon 3

Impatto: Medio Laravel 11 supporta sia Carbon 2 sia Carbon 3. Se aggiorni a Carbon 3, tieni presente che i metodi diffIn* restituiscono ora un valore in virgola mobile e la direzione del tempo è indicata da valori negativi.

Rate limiting

Rate limiting al secondo

Impatto: Medio Laravel 11 supporta il rate limiting al secondo oltre che al minuto. I costruttori delle classi GlobalLimit e Limit ricevono ora un valore in secondi.
// Prima (in minuti)
new GlobalLimit($attempts, 2); // 2 minuti

// Dopo (in secondi)
new GlobalLimit($attempts, 2 * 60); // 120 secondi
La proprietà decayMinutes della classe Limit è stata rinominata in decaySeconds ed è ora in secondi. Anche i costruttori di ThrottlesExceptions e ThrottlesExceptionsWithRedis ricevono ora un valore in secondi.
new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Pacchetti

Pubblicazione dei service provider

Impatto: Molto basso Nelle nuove app Laravel 11 non c’è più l’array providers in config/app.php. Se in un pacchetto pubblichi service provider, usa il metodo ServiceProvider::addProviderToBootstrapFile.
use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Sanctum

Aggiornamento di Sanctum

Impatto: Alto Laravel 11 non supporta Sanctum 3.x. Aggiorna la dipendenza di Sanctum in composer.json a ^4.0. Sanctum 4.0 non carica più automaticamente le migration. Pubblicale con il comando seguente.
php artisan vendor:publish --tag=sanctum-migrations
Aggiorna inoltre la configurazione middleware in config/sanctum.php.
'middleware' => [
    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
],

Pacchetto Spatie Once

Impatto: Medio Laravel 11 fornisce la propria funzione once. Se usi il pacchetto spatie/once, rimuovilo da composer.json per evitare conflitti.

Conclusioni

Laravel 11 include modifiche strutturali importanti, ma la struttura di app di Laravel 10 continua a funzionare, quindi puoi migrare in modo graduale.
ModificaImpattoAzione
Aggiornamento dipendenze in composer.jsonAltoPassa a laravel/framework ^11.0
PHP 8.2 richiestoAltoVerifica la versione di PHP
Attributi al cambio di colonnaAltoControlla i punti che usano change()
Tipi in virgola mobileAltoVerifica le definizioni delle colonne double/float
SQLite 3.26.0+ richiestoAltoControlla la versione di SQLite
Sanctum ^4.0AltoPubblica le migration
Carbon 3MedioControlla i valori di ritorno dei metodi diffIn*
Rate limiting al secondoMedioCambia decayMinutes in decaySeconds
Rimozione di Doctrine DBALBassoMigra ai metodi nativi dello schema

Riferimenti

Ultima modifica il 13 luglio 2026