Mise à niveau de Laravel 10 à 11 - Knowledge of Laravel

Introduction

Laravel 11 est sorti en mars 2024. Ce guide explique la procédure de mise à niveau de Laravel 10.x vers 11.x.

Le temps estimé de la mise à niveau est d’environ 15 minutes. L’impact des changements cassants dépend cependant de la taille de l’application et des fonctionnalités utilisées.

Mise à niveau automatisée avec Laravel Shift

Vous pouvez automatiser la mise à niveau avec Laravel Shift. Il met à jour automatiquement dépendances et fichiers de configuration.

Changements par impact

Impact élevé

Mise à jour des dépendances
Changements de structure applicative
Type flottant
Préservation des attributs lors de la modification d’une colonne
Version minimale de SQLite
Mise à jour de Sanctum

Impact moyen

Carbon 3
Re-hash des mots de passe
Rate limiting à la seconde
Package Spatie Once

Impact faible

Suppression de Doctrine DBAL
Méthode casts sur les modèles Eloquent
Changements sur les types spatiaux
Contract Enumerable
Contract UserProvider
Contract Authenticatable

Étapes de mise à niveau

Mise à jour des dépendances

Impact : élevé Mettez à jour les dépendances suivantes dans composer.json.

{
  "require": {
    "laravel/framework": "^11.0",
    "nunomaduro/collision": "^8.1"
  }
}

Mettez à jour les packages utilisés en conséquence.

{
  "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"
  }
}

Installez les dépendances :

composer update

Si vous utilisez Cashier Stripe, Passport, Sanctum, Spark Stripe ou Telescope, publiez leurs migrations dans l’application.

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

Si vous utilisez l’installer Laravel, mettez-le à jour.

composer global require laravel/installer:^5.6

Si vous aviez ajouté manuellement doctrine/dbal, vous pouvez le retirer : Laravel 11 n’en dépend plus.

Exigence de version PHP

Impact : élevé Laravel 11 nécessite PHP 8.2.0 ou supérieur. Le client HTTP Laravel nécessite curl 7.34.0 ou supérieur.

Changements de structure applicative

Impact : élevé Laravel 11 simplifie la structure applicative par défaut : nombre réduit de service providers, middlewares et fichiers de configuration. Il n’est cependant pas recommandé de tenter de migrer la structure applicative de Laravel 10 à 11 lors de la mise à niveau. Laravel 11 supporte la structure Laravel 10 telle quelle. Principaux changements structurels :

Middlewares, exception handler et routing se configurent désormais directement dans bootstrap/app.php
app/Http/Kernel.php est retiré, intégré à bootstrap/app.php
Le nombre de providers par défaut est réduit et géré via bootstrap/providers.php
Le nombre de fichiers dans config/ est réduit (php artisan config:publish permet de les publier au besoin)

Changements cassants

Authentification

Re-hash des mots de passe

Impact : moyen Depuis Laravel 11, si le « work factor » de l’algorithme de hash a changé, le mot de passe est re-haché automatiquement lors de la connexion. Si le champ mot de passe du modèle User n’est pas password, indiquez-le via la propriété authPasswordName.

class User extends Authenticatable
{
    protected $authPasswordName = 'custom_password_field';
}

Pour désactiver le comportement, ajoutez dans config/hashing.php :

'rehash_on_login' => false,

Contract `UserProvider`

Impact : faible Le contract Illuminate\Contracts\Auth\UserProvider gagne la méthode rehashPasswordIfRequired. Si vous l’implémentez ailleurs, ajoutez la méthode.

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

Contract `Authenticatable`

Impact : faible Le contract Illuminate\Contracts\Auth\Authenticatable gagne la méthode getAuthPasswordName. Ajoutez-la si nécessaire.

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

Base de données

Version minimale de SQLite

Impact : élevé En cas d’utilisation de SQLite, il faut SQLite 3.26.0 ou supérieur. Par ailleurs, dans un nouveau projet Laravel 11, le driver par défaut devient SQLite.

Préservation des attributs lors de la modification d’une colonne

Impact : élevé Lorsque vous modifiez une colonne, vous devez déclarer explicitement tous les modificateurs à conserver. Les attributs non spécifiés sont supprimés.

// Sur Laravel 10, unsigned, default, comment étaient préservés
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

// Sur Laravel 11, il faut spécifier tous les attributs
Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});

Si vous ne voulez pas mettre à jour toutes les migrations, faites un squash.

php artisan schema:dump

Type flottant

Impact : élevé Les types de colonnes double et float sont uniformisés sur toutes les bases de données.

// double : plus besoin des arguments total / places
$table->double('amount');

// float : argument optionnel de précision
$table->float('amount', precision: 53);

Les méthodes unsignedDecimal, unsignedDouble, unsignedFloat sont supprimées. Pour l’attribut unsigned, chaînez-le.

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

Méthode `casts` sur les modèles Eloquent

Impact : faible La classe de base des modèles Eloquent définit désormais la méthode casts. Si vous aviez une relation nommée casts, il faut la renommer.

Driver dédié MariaDB

Impact : très faible Laravel 11 ajoute un driver dédié MariaDB. Pour vous y connecter, utilisez la config mariadb.

'driver' => 'mariadb',

Changements sur les types spatiaux

Impact : faible Les types spatiaux sont uniformisés. Utilisez geometry ou geography à la place de point, lineString, polygon, etc.

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

Pour spécifier le sous-type et le SRID :

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

Suppression de Doctrine DBAL

Impact : faible Laravel n’utilise plus Doctrine DBAL. Sont supprimés :

Schema\Builder::useNativeSchemaOperationsIfPossible()
Connection::getDoctrineConnection()
Connection::getDoctrineSchemaManager()
Connection::registerDoctrineType()
DatabaseManager::registerDoctrineType()
Classe Schema\Grammars\ChangeColumn
Classe Schema\Grammars\RenameColumn

Pour introspecter la base, utilisez les nouvelles méthodes natives : Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys(), etc.

Dates

Carbon 3

Impact : moyen Laravel 11 supporte Carbon 2 et Carbon 3. Si vous passez à Carbon 3, notez que les méthodes diffIn* renvoient des flottants et représentent le sens du temps par le signe.

Rate limiting

Rate limiting à la seconde

Impact : moyen Laravel 11 supporte le rate limiting à la seconde. Les constructeurs des classes GlobalLimit et Limit acceptent désormais des secondes.

// Avant (minutes)
new GlobalLimit($attempts, 2); // 2 minutes

// Après (secondes)
new GlobalLimit($attempts, 2 * 60); // 120 secondes

La propriété decayMinutes de la classe Limit devient decaySeconds, en secondes. Les constructeurs de ThrottlesExceptions et ThrottlesExceptionsWithRedis acceptent également des secondes.

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

Packages

Publication de service providers

Impact : très faible Une nouvelle application Laravel 11 n’a plus le tableau providers dans config/app.php. Pour qu’un package publie un service provider, utilisez ServiceProvider::addProviderToBootstrapFile.

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Sanctum

Mise à jour de Sanctum

Impact : élevé Laravel 11 ne supporte pas Sanctum 3.x. Mettez à jour la dépendance vers ^4.0. Sanctum 4.0 ne charge plus automatiquement les migrations. Publiez-les :

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

Mettez à jour la configuration middleware dans 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,
],

Package Spatie Once

Impact : moyen Laravel 11 fournit sa propre fonction once. Si vous utilisez le package spatie/once, retirez-le du composer.json pour éviter les conflits.

Conclusion

Laravel 11 comporte des changements structurels importants, mais la structure Laravel 10 reste supportée : la migration peut être progressive.

Changement	Impact	À faire
Mise à jour de `composer.json`	Élevé	`laravel/framework ^11.0`
PHP 8.2 requis	Élevé	Vérifier la version PHP
Préservation des attributs de colonne	Élevé	Auditer les usages de `change()`
Type flottant	Élevé	Vérifier les colonnes `double`/`float`
SQLite 3.26.0+ requis	Élevé	Vérifier la version SQLite
Sanctum `^4.0`	Élevé	Publier les migrations
Carbon 3	Moyen	Vérifier le retour des `diffIn*`
Rate limiting à la seconde	Moyen	`decayMinutes` → `decaySeconds`
Suppression de Doctrine DBAL	Faible	Migrer vers les méthodes natives de schéma

Ressources

Guide officiel de mise à niveau (anglais)
Diff du dépôt laravel/laravel (10.x → 11.x)
Laravel Shift — service communautaire d’automatisation de la mise à niveau
Changelog Carbon 3

​Introduction

​Mise à niveau automatisée avec Laravel Shift

​Changements par impact

​Impact élevé

​Impact moyen

​Impact faible

​Étapes de mise à niveau

​Mise à jour des dépendances

​Exigence de version PHP

​Changements de structure applicative

​Changements cassants

​Authentification

​Re-hash des mots de passe

​Contract UserProvider

​Contract Authenticatable

​Base de données

​Version minimale de SQLite

​Préservation des attributs lors de la modification d’une colonne

​Type flottant

​Méthode casts sur les modèles Eloquent

​Driver dédié MariaDB

​Changements sur les types spatiaux

​Suppression de Doctrine DBAL

​Dates

​Carbon 3

​Rate limiting

​Rate limiting à la seconde

​Packages

​Publication de service providers

​Sanctum

​Mise à jour de Sanctum

​Package Spatie Once

​Conclusion

​Ressources

Introduction

Mise à niveau automatisée avec Laravel Shift

Changements par impact

Impact élevé

Impact moyen

Impact faible

Étapes de mise à niveau

Mise à jour des dépendances

Exigence de version PHP

Changements de structure applicative

Changements cassants

Authentification

Re-hash des mots de passe

Contract `UserProvider`

Contract `Authenticatable`

Base de données

Version minimale de SQLite

Préservation des attributs lors de la modification d’une colonne

Type flottant

Méthode `casts` sur les modèles Eloquent

Driver dédié MariaDB

Changements sur les types spatiaux

Suppression de Doctrine DBAL

Dates

Carbon 3

Rate limiting

Rate limiting à la seconde

Packages

Publication de service providers

Sanctum

Mise à jour de Sanctum

Package Spatie Once

Conclusion

Ressources