Aggiornamento

Cambiamenti ad Alto Impatto

Cambiamenti a Medio Impatto

Cambiamenti a Basso Impatto

Aggiornamento da 10.x a 11.0

Tempo Stimato per l’Aggiornamento: 15 Minuti

Cerchiamo di documentare ogni possibile cambiamento che potrebbe causare problemi. Poiché alcuni di questi cambiamenti si trovano in parti poco conosciute del framework, solo una parte di essi potrebbe effettivamente influenzare la tua applicazione. Vuoi risparmiare tempo? Puoi usare Laravel Shift per automatizzare gli aggiornamenti della tua applicazione.

Aggiornamento delle dipendenze

Probabilità di impatto: Alta

PHP 8.2.0 Necessario

Laravel richiede adesso PHP 8.2.0 o superiore.

curl 7.34.0

Il client HTTP di Laravel ora richiede curl 7.34.0 o superiore.

Dipendenze Composer

Devi aggiornare le seguenti dipendenze nel file composer.json della tua applicazione:

  • laravel/framework a ^11.0
  • nunomaduro/collision a ^8.1
  • laravel/breeze a ^2.0 (Se installato)
  • laravel/cashier a ^15.0 (Se installato)
  • laravel/dusk a ^8.0 (Se installato)
  • laravel/jetstream a ^5.0 (Se installato)
  • laravel/octane a ^2.3 (Se installato)
  • laravel/passport a ^12.0 (Se installato)
  • laravel/sanctum a ^4.0 (Se installato)
  • laravel/scout a ^10.0 (Se installato)
  • laravel/spark-stripe a ^5.0 (Se installato)
  • laravel/telescope a ^5.0 (Se installato)
  • livewire/livewire a ^3.4 (Se installato)
  • inertiajs/inertia-laravel a ^1.0 (Se installato)

Se la tua applicazione utilizza Laravel Cashier Stripe, Passport, Sanctum, Spark Stripe o Telescope, sarà necessario pubblicare le loro migrazioni nella tua applicazione. Cashier Stripe, Passport, Sanctum, Spark Stripe e Telescope non caricano più automaticamente le migrazioni dalla propria directory di migrazioni. Pertanto, dovresti eseguire il seguente comando per pubblicare le loro migrazioni nella tua 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

Inoltre, dovresti consultare le guide di aggiornamento per ciascuno di questi package per assicurarti di essere a conoscenza di eventuali cambiamenti importanti:

Se hai installato manualmente l’installer di Laravel, dovresti aggiornare l’installer tramite Composer:

composer global require laravel/installer:^5.6

Infine, puoi rimuovere la dipendenza Composer doctrine/dbal se l’hai precedentemente aggiunta alla tua applicazione, poiché Laravel non dipende più da questo package.

Struttura dell’Applicazione

Laravel 11 introduce una nuova struttura predefinita con meno file di default. In particolare, le nuove applicazioni Laravel includono meno service providers, middleware e file di configurazione.

Tuttavia, non raccomandiamo che le applicazioni Laravel 10 che aggiornano a Laravel 11 tentino di migrare la loro struttura, poiché Laravel 11 è stato attentamente ottimizzato per supportare anche la struttura delle applicazioni Laravel 10.

Autenticazione

Ricalcolo delle Password

Probabilità di Impatto: Bassa

Laravel 11 ricalcolerà automaticamente le password degli utenti durante l’autenticazione se il "work factor" dell’algoritmo di hashing è stato aggiornato da quando la password è stata hashata l’ultima volta.

In genere, questo non dovrebbe interrompere la tua applicazione; tuttavia, se il campo "password" del tuo modello User ha un nome diverso da password, dovresti specificare il nome del campo tramite la proprietà authPasswordName del modello:

protected $authPasswordName = 'custom_password_field';

In alternativa, puoi disabilitare il ricalcolo delle password aggiungendo l’opzione rehash_on_login nel file di configurazione config/hashing.php della tua applicazione:

'rehash_on_login' => false,

Il Contratto UserProvider

Probabilità di Impatto: Bassa

Il contratto Illuminate\Contracts\Auth\UserProvider ha ora un nuovo metodo rehashPasswordIfRequired. Questo metodo è responsabile del re-hashing e del salvataggio della password dell’utente nello storage quando il work-factor dell’algoritmo di hashing dell’applicazione è cambiato.

Se la tua applicazione o pacchetto definisce una classe che implementa questa interfaccia, dovresti aggiungere il nuovo metodo rehashPasswordIfRequired alla tua implementazione. Un’implementazione di riferimento si trova nella classe Illuminate\Auth\EloquentUserProvider:

public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

Il Contratto Authenticatable

Probabilità di Impatto: Bassa

Il contratto Illuminate\Contracts\Auth\Authenticatable ha ora un nuovo metodo getAuthPasswordName. Questo metodo è responsabile di restituire il nome della colonna della password della tua entità autenticabile.

Se la tua applicazione o package definisce una classe che implementa questa interfaccia, dovresti aggiungere il nuovo metodo getAuthPasswordName alla tua implementazione:

public function getAuthPasswordName()
{
    return 'password';
}

Il modello predefinito User incluso in Laravel si ritrova automaticamente questo metodo poiché è incluso nel trait Illuminate\Auth\Authenticatable.

La classe AuthenticationException

Probabilità di Impatto: Molto Bassa

Il metodo redirectTo della classe Illuminate\Auth\AuthenticationException ora richiede un’istanza di Illuminate\Http\Request come primo argomento. Se stai gestendo manualmente questa eccezione e chiamando il metodo redirectTo, dovresti aggiornare il tuo codice di conseguenza:

if ($e instanceof AuthenticationException) {
    $path = $e->redirectTo($request);
}

Notifica di Verifica Email alla Registrazione

Probabilità di Impatto: Molto Bassa

Il listener SendEmailVerificationNotification viene ora registrato automaticamente per l’evento Registered se non è già registrato nel EventServiceProvider della tua applicazione. Se il EventServiceProvider della tua applicazione non registra questo listener e non desideri che Laravel lo registri automaticamente per te, dovresti definire un metodo configureEmailVerification vuoto nell’EventServiceProvider della tua applicazione:

protected function configureEmailVerification()
{
    // ...
}

Cache

Prefissi delle Chiavi Cache

Probabilità di Impatto: Molto Bassa

In precedenza, se veniva definito un prefisso per le chiavi cache nei negozi DynamoDB, Memcached o Redis, Laravel aggiungeva : al prefisso. In Laravel 11, il prefisso delle chiavi cache non riceve più il suffisso :. Se desideri mantenere il comportamento precedente, puoi aggiungere manualmente il suffisso : al tuo prefisso delle chiavi cache.

Collezioni

Il contratto Enumerable

Probabilità di impatto: Bassa

Il metodo dump del contratto Illuminate\Support\Enumerable è stato aggiornato per accettare un argomento variadico ...$args. Se stai implementando questa interfaccia, dovresti aggiornare la tua implementazione di conseguenza:

public function dump(...$args);

Database

SQLite 3.26.0+

Probabilità di impatto: Alta

Se la tua applicazione utilizza un database SQLite, è necessario SQLite 3.26.0 o superiore.

Metodo casts del Modello Eloquent

Probabilità di Impatto: Bassa

La classe base del modello Eloquent ora include un metodo casts per gestire i cast degli attributi. Se uno dei modelli della tua applicazione utilizza una relazione casts, potrebbe entrare in conflitto con il metodo casts presente nella classe base del modello Eloquent.

Modifica delle Colonne

Probabilità di Impatto: Alta

Quando modifichi una colonna, devi ora includere esplicitamente tutti i modificatori che desideri mantenere nella definizione della colonna dopo il cambiamento. Qualsiasi attributo mancante verrà rimosso. Ad esempio, per mantenere gli attributi unsigned, default e comment, devi chiamare ogni modificatore esplicitamente quando cambi la colonna, anche se questi attributi sono stati assegnati alla colonna da una migrazione precedente.

Per esempio, immagina di avere una migrazione che crea una colonna votes con gli attributi unsigned, default e comment:

Schema::create('users', function (Blueprint $table) {
    $table->integer('votes')->unsigned()->default(1)->comment('The vote count');
});

Successivamente, scrivi una migrazione che aggiunge anche nullable alla colonna:

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

In Laravel 10, questa migrazione manteneva gli attributi unsigned, default e comment sulla colonna. Tuttavia, in Laravel 11, la migrazione deve ora includere anche tutti gli attributi precedentemente definiti sulla colonna. Altrimenti, verranno rimossi:

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});

Il metodo change non modifica gli indici della colonna. Pertanto, puoi usare i modificatori di indice per aggiungere o rimuovere esplicitamente un indice quando modifichi la colonna:

// Aggiungi un indice...
$table->bigIncrements('id')->primary()->change();

// Rimuovi un indice...
$table->char('postal_code', 10)->unique(false)->change();

Se non vuoi aggiornare tutte le migrazioni esistenti di "change" nella tua applicazione per mantenere gli attributi esistenti della colonna, puoi semplicemente "squashare" le tue migrazioni:

php artisan schema:dump

Una volta che le tue migrazioni sono state "squashate", Laravel "migrerà" il database utilizzando il file di schema della tua applicazione prima di eseguire eventuali migrazioni in sospeso.

Tipi in Virgola Mobile

Probabilità di Impatto: Alta

I tipi di colonna di migrazione double e float sono stati riscritti per essere coerenti su tutti i database.

Il tipo di colonna double ora crea una colonna equivalente DOUBLE senza cifre totali e posizioni (cifre dopo il punto decimale), che è la sintassi standard SQL. Pertanto, puoi rimuovere gli argomenti per $total e $places:

$table->double('amount');

Il tipo di colonna float ora crea una colonna equivalente FLOAT senza cifre totali e posizioni (cifre dopo il punto decimale), ma con una specifica opzionale $precision per determinare la dimensione di archiviazione come colonna a precisione singola da 4 byte o a precisione doppia da 8 byte. Pertanto, puoi rimuovere gli argomenti per $total e $places e specificare l’opzionale $precision al valore desiderato e secondo la documentazione del tuo database:

$table->float('amount', precision: 53);

I metodi unsignedDecimal, unsignedDouble e unsignedFloat sono stati rimossi, poiché il modificatore unsigned per questi tipi di colonna è stato deprecato da MySQL e non è mai stato standardizzato su altri sistemi di database. Tuttavia, se desideri continuare a utilizzare l’attributo unsigned deprecato per questi tipi di colonna, puoi concatenare il metodo unsigned alla definizione della colonna:

$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();

Driver dedicato per MariaDB

Probabilità di impatto: Molto Bassa

Invece di utilizzare sempre il driver MySQL per connettersi ai database MariaDB, Laravel 11 introduce un driver dedicato per MariaDB.

Se la tua applicazione si connette a un database MariaDB, puoi aggiornare la configurazione della connessione al nuovo driver mariadb per beneficiare delle funzionalità specifiche di MariaDB in futuro:

    'driver' => 'mariadb',
    'url' => env('DB_URL'),
    'host' => env('DB_HOST', '127.0.0.1'),
    'port' => env('DB_PORT', '3306'),
    // ...

Attualmente, il nuovo driver MariaDB si comporta come l’attuale driver MySQL con un’eccezione: il metodo uuid del builder dello schema crea colonne UUID native invece di colonne char(36).

Se le tue migrazioni esistenti utilizzano il metodo uuid del builder dello schema e scegli di usare il nuovo driver del database mariadb, dovresti aggiornare le invocazioni del metodo uuid nelle migrazioni a char per evitare cambiamenti che possano causare problemi o comportamenti inaspettati:

Schema::table('users', function (Blueprint $table) {
    $table->char('uuid', 36);

    // ...
});

Tipi Spaziali

Probabilità di Impatto: Bassa

I tipi di colonne spaziali delle migrazioni del database sono stati riscritti per essere coerenti su tutti i database. Pertanto, puoi rimuovere i metodi point, lineString, polygon, geometryCollection, multiPoint, multiLineString, multiPolygon e multiPolygonZ dalle tue migrazioni e utilizzare invece i metodi geometry o geography:

$table->geometry('shapes');
$table->geography('coordinates');

Per restringere esplicitamente il tipo o l’identificatore del sistema di riferimento spaziale per i valori memorizzati nella colonna su MySQL, MariaDB e PostgreSQL, puoi passare subtype e srid al metodo:

$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);

I modificatori di colonna isGeometry e projection della grammatica di PostgreSQL sono stati rimossi di conseguenza.

Rimozione di Doctrine DBAL

Probabilità di impatto: Bassa

È stata rimossa la seguente lista di classi e metodi legati a Doctrine DBAL. Laravel non dipende più da questo package e registrare tipi custom di Doctrine non è più necessario per la corretta creazione e modifica di vari tipi di colonne che in precedenza richiedevano tipi custom:

  • Proprietà della classe Illuminate\Database\Schema\Builder::$alwaysUsesNativeSchemaOperationsIfPossible
  • Metodo Illuminate\Database\Schema\Builder::useNativeSchemaOperationsIfPossible()
  • Metodo Illuminate\Database\Connection::usingNativeSchemaOperations()
  • Metodo Illuminate\Database\Connection::isDoctrineAvailable()
  • Metodo Illuminate\Database\Connection::getDoctrineConnection()
  • Metodo Illuminate\Database\Connection::getDoctrineSchemaManager()
  • Metodo Illuminate\Database\Connection::getDoctrineColumn()
  • Metodo Illuminate\Database\Connection::registerDoctrineType()
  • Metodo Illuminate\Database\DatabaseManager::registerDoctrineType()
  • Directory Illuminate\Database\PDO
  • Classe Illuminate\Database\DBAL\TimestampType
  • Classe Illuminate\Database\Schema\Grammars\ChangeColumn
  • Classe Illuminate\Database\Schema\Grammars\RenameColumn
  • Metodo Illuminate\Database\Schema\Grammars\Grammar::getDoctrineTableDiff()

Inoltre, non è più necessario registrare tipi custom di Doctrine tramite dbal.types nel file di configurazione database della tua applicazione.

Se utilizzavi precedentemente Doctrine DBAL per ispezionare il tuo database e le relative tabelle, puoi usare i nuovi metodi nativi di schema di Laravel (Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys(), ecc.).

Metodi Schema Deprecati

Probabilità di Impatto: Molto Bassa

I metodi obsoleti basati su Doctrine Schema::getAllTables(), Schema::getAllViews() e Schema::getAllTypes() sono stati rimossi a favore dei nuovi metodi nativi di Laravel Schema::getTables(), Schema::getViews() e Schema::getTypes().

Quando si utilizzano PostgreSQL e SQL Server, nessuno dei nuovi metodi dello schema accetterà un riferimento a tre parti (es. database.schema.table). Pertanto, dovresti usare connection() per dichiarare il database invece:

Schema::connection('database')->hasTable('schema.table');

Metodo getColumnType() di Schema Builder

Probabilità di Impatto: Molto Bassa

Il metodo Schema::getColumnType() restituisce ora sempre il tipo reale della colonna specificata, e non il tipo equivalente di Doctrine DBAL.

Interfaccia di Connessione al Database

Probabilità di Impatto: Molto Bassa

L’interfaccia Illuminate\Database\ConnectionInterface ha ricevuto un nuovo metodo scalar. Se stai definendo una tua implementazione di questa interfaccia, dovresti aggiungere il metodo scalar alla tua implementazione:

public function scalar($query, $bindings = [], $useReadPdo = true);

Date

Carbon 3

Probabilità di impatto: Medio

Laravel 11 supporta sia Carbon 2 che Carbon 3. Carbon è una libreria per la manipolazione delle date ampiamente utilizzata da Laravel e dai package dell’ecosistema. Se aggiorni a Carbon 3, sappi che i metodi diffIn* ora restituiscono numeri in virgola mobile e potrebbero restituire valori negativi per indicare la direzione del tempo, una modifica significativa rispetto a Carbon 2. Consulta il registro delle modifiche e la documentazione di Carbon per informazioni dettagliate su come gestire questi e altri cambiamenti.

Mail

Il Contratto Mailer

Probabilità di Impatto: Molto Bassa

Il contratto Illuminate\Contracts\Mail\Mailer ha ricevuto un nuovo metodo sendNow. Se la tua applicazione o pacchetto sta implementando manualmente questo contratto, dovresti aggiungere il nuovo metodo sendNow alla tua implementazione:

public function sendNow($mailable, array $data = [], $callback = null);

Package

Pubblicare i Service Provider nell’Applicazione

Probabilità di Impatto: Molto Bassa

Se hai creato un package Laravel che pubblica manualmente un service provider nella directory app/Providers dell’applicazione e modifica manualmente il file di configurazione config/app.php per registrare il service provider, dovresti aggiornare il tuo pacchetto per utilizzare il nuovo metodo ServiceProvider::addProviderToBootstrapFile.

Il metodo addProviderToBootstrapFile aggiungerà automaticamente il service provider che hai pubblicato al file bootstrap/providers.php dell’applicazione, poiché l’array providers non esiste più nel file di configurazione config/app.php nelle nuove applicazioni Laravel 11.

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Code

L’Interfaccia BatchRepository

Probabilità di Impatto: Molto Bassa

L’interfaccia Illuminate\Bus\BatchRepository ha ricevuto un nuovo metodo rollBack. Se stai implementando questa interfaccia nel tuo pacchetto o applicazione, dovresti aggiungere questo metodo alla tua implementazione:

public function rollBack();

Job Sincroni nelle Transazioni del Database

Probabilità di Impatto: Molto Bassa

In precedenza, i job sincroni (job che utilizzano il driver di coda sync) venivano eseguiti immediatamente, indipendentemente dal fatto che l’opzione di configurazione after_commit della connessione coda fosse impostata su true o che il metodo afterCommit fosse invocato sul job.

In Laravel 11, i job sincroni della coda ora rispetteranno la configurazione "after commit" della connessione coda o del job.

Limitazione delle richieste

Limitazione del Rate per Secondo

Probabilità di Impatto: Medio

Laravel 11 supporta la limitazione del rate per secondo invece di essere limitato alla granularità per minuto. Ci sono diverse possibili modifiche che potrebbero causare problemi di cui dovresti essere a conoscenza in relazione a questo cambiamento.

Il costruttore della classe GlobalLimit ora accetta secondi invece di minuti. Questa classe non è documentata e non viene solitamente utilizzata dalla tua applicazione:

new GlobalLimit($attempts, 2 * 60);

Il costruttore della classe Limit ora accetta secondi invece di minuti. Tutti gli usi documentati di questa classe sono limitati a costruttori statici come Limit::perMinute e Limit::perSecond. Tuttavia, se stai istanziando questa classe manualmente, dovresti aggiornare la tua applicazione per fornire secondi al costruttore della classe:

new Limit($key, $attempts, 2 * 60);

La proprietà decayMinutes della classe Limit è stata rinominata in decaySeconds e ora contiene secondi invece di minuti.

I costruttori delle classi Illuminate\Queue\Middleware\ThrottlesExceptions e Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis ora accettano secondi invece di minuti:

new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Cashier Stripe

Aggiornamento di Cashier Stripe

Probabilità di impatto: Alta

Laravel 11 non supporta più Cashier Stripe 14.x. Pertanto, dovresti aggiornare la dipendenza Laravel Cashier Stripe della tua applicazione a ^15.0 nel tuo file composer.json.

Cashier Stripe 15.0 non carica più automaticamente le migrazioni dalla propria directory di migrazioni. Invece, dovresti eseguire il seguente comando per pubblicare le migrazioni di Cashier Stripe nella tua applicazione:

php artisan vendor:publish --tag=cashier-migrations

Per favore, consulta la guida completa all’aggiornamento di Cashier Stripe per ulteriori informazioni.

Spark (Stripe)

Aggiornamento di Spark Stripe

Probabilità di impatto: Alta

Laravel 11 non supporta più Laravel Spark Stripe 4.x. Pertanto, dovresti aggiornare la dipendenza Laravel Spark Stripe della tua applicazione a ^5.0 nel tuo file composer.json.

Spark Stripe 5.0 non carica più automaticamente le migrazioni dalla propria directory delle migrazioni. Invece, dovresti eseguire il seguente comando per pubblicare le migrazioni di Spark Stripe nella tua applicazione:

php artisan vendor:publish --tag=spark-migrations

Per favore, consulta la guida completa all’aggiornamento di Spark Stripe per ulteriori informazioni.

Passport

Aggiornamento di Passport

Probabilità di impatto: Alta

Laravel 11 non supporta più Laravel Passport 11.x. Pertanto, dovresti aggiornare la dipendenza Laravel Passport della tua applicazione a ^12.0 nel file composer.json.

Passport 12.0 non carica più automaticamente le migrazioni dalla propria directory. Invece, dovresti eseguire il seguente comando per pubblicare le migrazioni di Passport nella tua applicazione:

php artisan vendor:publish --tag=passport-migrations

Inoltre, il tipo di grant password è disabilitato di default. Puoi abilitarlo chiamando il metodo enablePasswordGrant nel metodo boot del AppServiceProvider della tua applicazione:

    public function boot(): void
    {
        Passport::enablePasswordGrant();
    }

Sanctum

Aggiornare Sanctum

Probabilità di impatto: Alta

Laravel 11 non supporta più Laravel Sanctum 3.x. Pertanto, dovresti aggiornare la dipendenza Laravel Sanctum della tua applicazione a ^4.0 nel file composer.json.

Sanctum 4.0 non carica più automaticamente le migrazioni dalla sua directory. Invece, devi eseguire il seguente comando per pubblicare le migrazioni di Sanctum nella tua applicazione:

php artisan vendor:publish --tag=sanctum-migrations

Successivamente, nel file di configurazione config/sanctum.php della tua applicazione, aggiorna i riferimenti ai middleware authenticate_session, encrypt_cookies e validate_csrf_token come segue:

    '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,
    ],

Telescope

Aggiornamento di Telescope

Probabilità di Impatto: Alta

Laravel 11 non supporta più Laravel Telescope 4.x. Pertanto, dovresti aggiornare la dipendenza di Laravel Telescope della tua applicazione a ^5.0 nel file composer.json.

Telescope 5.0 non carica più automaticamente le migrazioni dalla propria directory. Invece, dovresti eseguire il seguente comando per pubblicare le migrazioni di Telescope nella tua applicazione:

php artisan vendor:publish --tag=telescope-migrations

Pacchetto Spatie Once

Probabilità di impatto: Medio

Laravel 11 fornisce ora la propria once function per garantire che una determinata closure venga eseguita solo una volta. Pertanto, se la tua applicazione dipende dal pacchetto spatie/once, dovresti rimuoverlo dal file composer.json della tua applicazione per evitare conflitti.

Varie

Vi consigliamo anche di visualizzare le modifiche nel repository GitHub laravel/laravel. Anche se molte di queste modifiche non sono obbligatorie, potrebbe essere utile mantenere questi file sincronizzati con la vostra applicazione. Alcune di queste modifiche saranno trattate in questa guida all’aggiornamento, ma altre, come le modifiche ai file di configurazione o ai commenti, no. Potete facilmente visualizzare le modifiche usando lo strumento di confronto di GitHub e scegliere quali aggiornamenti sono importanti per voi.

Lascia un commento

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *