Passer au contenu principal

Introduction

Laravel 10 a été publié le 14 février 2023. Ce guide décrit la procédure de mise à niveau de Laravel 9.x vers 10.x.
Le temps estimé pour la mise à niveau est d’environ 10 minutes. Cependant, l’impact des changements de rupture sur votre application varie selon sa taille et les fonctionnalités utilisées.

Mise à niveau automatisée avec Laravel Shift

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

Changements par niveau d’impact

Impact : élevé

  • Mise à jour des dépendances
  • Mise à jour de minimum-stability

Impact : moyen

  • Modification des expressions de base de données
  • Suppression de la propriété $dates des modèles
  • Monolog 3
  • Tags de cache Redis
  • Modification du service mocking
  • Répertoire de langues

Impact : faible

  • Messages des règles de validation basées sur des closures
  • Méthode after des form requests
  • Binding du public path
  • Constructeur de QueryException
  • Valeurs de retour du rate limiter
  • Suppression de la méthode Redirect::home
  • Suppression de la méthode Bus::dispatchNow
  • Méthode registerPolicies
  • Colonnes ULID

Procédure de mise à niveau

Mise à jour des dépendances

Impact : élevé Mettez à jour les dépendances suivantes dans composer.json.
{
  "require": {
    "laravel/framework": "^10.0",
    "laravel/sanctum": "^3.2",
    "doctrine/dbal": "^3.0",
    "spatie/laravel-ignition": "^2.0"
  }
}
Si vous utilisez ces paquets, mettez-les également à jour.
{
  "require": {
    "laravel/passport": "^11.0",
    "laravel/ui": "^4.0"
  }
}
Si vous utilisez PHPUnit 10, mettez également à jour ce qui suit.
{
  "require-dev": {
    "nunomaduro/collision": "^7.0",
    "phpunit/phpunit": "^10.0"
  }
}
Si vous utilisez PHPUnit 10, supprimez l’attribut processUncoveredFiles de la section <coverage> de phpunit.xml.
Après la mise à jour, installez les dépendances avec la commande suivante.
composer update
Pour la mise à niveau de Sanctum 2.x vers 3.x, consultez également le guide de mise à niveau Sanctum 3.x.

Mise à jour de minimum-stability

Impact : élevé Mettez à jour minimum-stability dans composer.json à stable. Comme la valeur par défaut est stable, vous pouvez également supprimer ce paramètre.
"minimum-stability": "stable"

Version requise de PHP

Impact : élevé Laravel 10 nécessite PHP 8.1.0 ou supérieur et Composer 2.2.0 ou supérieur.

Changements de rupture (Breaking Changes)

Application

Binding du public path

Impact : faible Si vous personnalisez le public path en bindant path.public dans le conteneur, modifiez-le pour utiliser la méthode usePublicPath de Illuminate\Foundation\Application.
app()->usePublicPath(__DIR__.'/public');

Autorisation

Méthode registerPolicies

Impact : faible La méthode registerPolicies du AuthServiceProvider est désormais appelée automatiquement par le framework. Vous pouvez supprimer son appel depuis la méthode boot.

Cache

Tags de cache Redis

Impact : moyen Cache::tags() n’est recommandé que pour les applications utilisant Memcached. Si vous utilisez Redis comme pilote de cache, envisagez une migration vers Memcached.

Base de données

Modification des expressions de base de données

Impact : moyen Les expressions de base de données générées par DB::raw ont été réécrites. Pour obtenir la valeur chaîne brute de l’expression, vous devez utiliser la méthode getValue(Grammar $grammar). La conversion vers (string) n’est plus possible.
use Illuminate\Support\Facades\DB;

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

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

// Après
$string = $expression->getValue(DB::connection()->getQueryGrammar());
Cela n’affecte généralement pas les applications utilisateur finales, mais une mise à jour est nécessaire si vous convertissez les expressions de base de données en chaîne.

Constructeur de QueryException

Impact : très faible Le nom de la connexion sous forme de chaîne a été ajouté comme premier argument du constructeur de Illuminate\Database\QueryException. Si vous lancez manuellement cette exception, corrigez votre code.

Colonnes ULID

Impact : faible Lorsque la méthode ulid est appelée sans argument dans une migration, le nom de la colonne devient ulid. Dans les versions précédentes, un appel sans argument créait par erreur une colonne nommée uuid.
// Le nom de colonne sera "ulid"
$table->ulid();

// Pour spécifier explicitement le nom de la colonne
$table->ulid('ulid');

Eloquent

Propriété $dates des modèles

Impact : moyen La propriété dépréciée $dates des modèles Eloquent a été supprimée. Utilisez la propriété $casts.
// Avant
protected $dates = ['deployed_at'];

// Après
protected $casts = [
    'deployed_at' => 'datetime',
];

Localisation

Répertoire de langues

Impact : aucun Cela n’affecte pas les applications existantes, mais le squelette des nouvelles applications Laravel n’inclut plus par défaut le répertoire lang. Vous pouvez le publier avec une commande Artisan si nécessaire.
php artisan lang:publish

Logs

Monolog 3

Impact : moyen La dépendance Monolog de Laravel a été mise à jour vers Monolog 3.x. Si vous utilisez directement Monolog dans votre application, consultez le guide de mise à niveau de Monolog. Si vous utilisez des services de logging tiers comme BugSnag ou Rollbar, une mise à niveau vers une version prenant en charge Monolog 3.x et Laravel 10.x peut être nécessaire.
Vous pouvez consulter les changements de Monolog 3.x dans le guide de mise à niveau Monolog 3.x.

File d’attente

Suppression de la méthode Bus::dispatchNow

Impact : faible Les méthodes dépréciées Bus::dispatchNow et dispatch_now ont été supprimées. Utilisez Bus::dispatchSync et dispatch_sync.
// Avant
Bus::dispatchNow(new MyJob());
dispatch_now(new MyJob());

// Après
Bus::dispatchSync(new MyJob());
dispatch_sync(new MyJob());

Routage

Alias de middleware

Impact : facultatif Dans les nouvelles applications Laravel, la propriété $routeMiddleware de la classe App\Http\Kernel a été renommée en $middlewareAliases. Son application aux applications existantes est facultative.

Valeur de retour du rate limiter

Impact : faible Lors de l’appel de la méthode RateLimiter::attempt, la valeur de retour de la closure fournie est désormais retournée telle quelle. Si vous ne retournez rien ou retournez null, true est retourné.
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Suppression de la méthode Redirect::home

Impact : très faible La méthode dépréciée Redirect::home a été supprimée. Redirigez explicitement vers une route nommée.
// Avant
return Redirect::home();

// Après
return Redirect::route('home');

Tests

Service mocking

Impact : moyen Le trait déprécié MocksApplicationServices a été supprimé du framework. Ce trait fournissait les méthodes de test comme expectsEvents, expectsJobs, expectsNotifications. Si vous utilisez ces méthodes, migrez respectivement vers Event::fake, Bus::fake, Notification::fake.
// Avant
$this->expectsEvents(OrderShipped::class);

// Après
Event::fake();
// ... code de test ...
Event::assertDispatched(OrderShipped::class);

Validation

Messages des règles de validation basées sur des closures

Impact : très faible Lorsque le callback $fail est appelé plusieurs fois dans une règle de validation personnalisée basée sur une closure, les messages sont désormais ajoutés à un tableau au lieu d’être écrasés. De plus, le callback $fail retourne désormais un objet. Si vous typez le retour de vos closures de validation, une mise à jour est nécessaire.
public function rules()
{
    return [
        'name' => [
            function ($attribute, $value, $fail) {
                $fail('validation.translation.key')->translate();
            },
        ],
    ];
}

Méthode after des form requests

Impact : très faible La méthode after dans les form requests est désormais réservée par Laravel. Si vous définissez une méthode after dans un form request, renommez-la ou modifiez-la pour tirer parti de la nouvelle fonctionnalité de validation « after ».

Résumé

Laravel 10 comprend des changements relativement mineurs, et la mise à niveau peut se faire rapidement.
ChangementImpactAction
Mise à jour des dépendances dans composer.jsonélevéPasser à laravel/framework ^10.0
PHP 8.1 / Composer 2.2 requisélevéVérifier et mettre à jour les versions
Modification des expressions de base de donnéesmoyenRemplacer la conversion (string) par getValue()
Suppression de la propriété $dates des modèlesmoyenMigrer vers $casts
Monolog 3moyenConsulter le guide de mise à niveau si vous l’utilisez directement
Tags de cache RedismoyenEnvisager la migration vers Memcached
Suppression de MocksApplicationServicesmoyenMigrer vers Event::fake etc.
Suppression de Bus::dispatchNowfaibleRemplacer par Bus::dispatchSync
Nom de colonne ULIDfaibleVérifier les appels à ulid() dans les migrations
Suppression de Redirect::hometrès faibleRemplacer par Redirect::route('home')

Ressources

Dernière modification le 13 juillet 2026