Zum Hauptinhalt springen

Einleitung

Laravel 10 wurde am 14. Februar 2023 veröffentlicht. Dieser Leitfaden beschreibt die Upgrade-Schritte von Laravel 9.x auf 10.x.
Der geschätzte Zeitaufwand liegt bei etwa 10 Minuten. Die tatsächliche Auswirkung der Breaking Changes hängt jedoch vom Umfang und den genutzten Funktionen ab.

Automatisches Upgrade mit Laravel Shift

Sie können das Upgrade auch mit Laravel Shift automatisieren. Shift aktualisiert Abhängigkeiten und Konfigurationsdateien der Anwendung automatisch.

Änderungen nach Auswirkung

Auswirkung: Hoch

  • Aktualisierung der Abhängigkeiten
  • Aktualisierung von minimum-stability

Auswirkung: Mittel

  • Änderungen an Datenbank-Expressions
  • Entfall der $dates-Property am Model
  • Monolog 3
  • Redis-Cache-Tags
  • Änderungen beim Service-Mocking
  • Sprachverzeichnis

Auswirkung: Niedrig

  • Meldungen bei Closure-basierten Validierungsregeln
  • Methode after in FormRequests
  • Public-Path-Binding
  • Konstruktor von QueryException
  • Rückgabewert des Rate Limiters
  • Entfall der Methode Redirect::home
  • Entfall der Methode Bus::dispatchNow
  • Methode registerPolicies
  • ULID-Spalte

Upgrade-Schritte

Abhängigkeiten aktualisieren

Auswirkung: Hoch Aktualisieren Sie in composer.json folgende Abhängigkeiten.
{
  "require": {
    "laravel/framework": "^10.0",
    "laravel/sanctum": "^3.2",
    "doctrine/dbal": "^3.0",
    "spatie/laravel-ignition": "^2.0"
  }
}
Wenn Sie zusätzliche Pakete nutzen, aktualisieren Sie diese ebenfalls.
{
  "require": {
    "laravel/passport": "^11.0",
    "laravel/ui": "^4.0"
  }
}
Beim Einsatz von PHPUnit 10:
{
  "require-dev": {
    "nunomaduro/collision": "^7.0",
    "phpunit/phpunit": "^10.0"
  }
}
Wenn Sie PHPUnit 10 verwenden, entfernen Sie im Abschnitt <coverage> der phpunit.xml das Attribut processUncoveredFiles.
Installieren Sie anschließend die Abhängigkeiten:
composer update
Für ein Upgrade von Sanctum 2.x auf 3.x konsultieren Sie den Sanctum-3.x-Upgrade-Guide.

minimum-stability aktualisieren

Auswirkung: Hoch Setzen Sie minimum-stability in composer.json auf stable. Da stable der Default ist, können Sie die Angabe auch entfernen.
"minimum-stability": "stable"

PHP-Version

Auswirkung: Hoch Laravel 10 benötigt PHP 8.1.0 oder höher und Composer 2.2.0 oder höher.

Breaking Changes

Anwendung

Public-Path-Binding

Auswirkung: Niedrig Wenn Sie den Public Path durch Binden von path.public an den Container angepasst haben, wechseln Sie auf die Methode usePublicPath von Illuminate\Foundation\Application.
app()->usePublicPath(__DIR__.'/public');

Autorisierung

Methode registerPolicies

Auswirkung: Niedrig Die Methode registerPolicies im AuthServiceProvider wird jetzt automatisch vom Framework aufgerufen. Sie können den Aufruf aus boot entfernen.

Cache

Redis-Cache-Tags

Auswirkung: Mittel Cache::tags() wird nur noch für Anwendungen empfohlen, die Memcached nutzen. Wenn Sie Redis als Cache-Treiber verwenden, prüfen Sie einen Umstieg auf Memcached.

Datenbank

Änderungen an Datenbank-Expressions

Auswirkung: Mittel Die durch DB::raw erzeugten Datenbank-Expressions wurden neu implementiert. Zum Auslesen des rohen String-Werts verwenden Sie nun getValue(Grammar $grammar); ein Cast per (string) ist nicht mehr möglich.
use Illuminate\Support\Facades\DB;

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

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

// Nachher
$string = $expression->getValue(DB::connection()->getQueryGrammar());
Endanwenderanwendungen sind meist nicht betroffen; wenn Sie Datenbank-Expressions in Strings casten, ist eine Anpassung nötig.

Konstruktor von QueryException

Auswirkung: Sehr niedrig Der erste Konstruktor-Parameter von Illuminate\Database\QueryException ist nun ein String mit dem Connection-Namen. Werfen Sie die Exception manuell, passen Sie den Code entsprechend an.

ULID-Spalte

Auswirkung: Niedrig Wenn Sie in Migrationen ulid ohne Argument aufrufen, heißt die Spalte nun ulid. In früheren Releases wurde stattdessen fälschlich eine uuid-Spalte erzeugt.
// Der Spaltenname lautet "ulid"
$table->ulid();

// Explizit einen Namen angeben
$table->ulid('ulid');

Eloquent

$dates-Property am Model

Auswirkung: Mittel Die veraltete Property $dates an Eloquent-Modellen wurde entfernt. Verwenden Sie $casts.
// Vorher
protected $dates = ['deployed_at'];

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

Lokalisierung

Sprachverzeichnis

Auswirkung: Keine Bestehende Anwendungen sind nicht betroffen; im neuen Skelett von Laravel ist das Verzeichnis lang standardmäßig nicht enthalten. Bei Bedarf veröffentlichen Sie es per Artisan.
php artisan lang:publish

Logging

Monolog 3

Auswirkung: Mittel Die Monolog-Abhängigkeit von Laravel wurde auf Monolog 3.x aktualisiert. Wenn Sie Monolog direkt in Ihrer Anwendung verwenden, konsultieren Sie den Monolog-Upgrade-Guide. Für Drittanbieter-Logging-Dienste wie BugSnag oder Rollbar benötigen Sie möglicherweise Versionen, die Monolog 3.x und Laravel 10.x unterstützen.
Änderungen von Monolog 3.x finden Sie im Monolog-3.x-Upgrade-Guide.

Queue

Entfall der Methode Bus::dispatchNow

Auswirkung: Niedrig Die veralteten Methoden Bus::dispatchNow und dispatch_now wurden entfernt. Verwenden Sie Bus::dispatchSync bzw. dispatch_sync.
// Vorher
Bus::dispatchNow(new MyJob());
dispatch_now(new MyJob());

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

Routing

Middleware-Aliases

Auswirkung: Optional In neuen Laravel-Anwendungen heißt die Property $routeMiddleware der Klasse App\Http\Kernel nun $middlewareAliases. Die Übernahme in bestehende Anwendungen ist optional.

Rückgabewert des Rate Limiters

Auswirkung: Niedrig Beim Aufruf von RateLimiter::attempt wird der Rückgabewert der übergebenen Closure jetzt direkt zurückgereicht. Wenn nichts oder null zurückgegeben wird, ist der Rückgabewert true.
$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Entfall der Methode Redirect::home

Auswirkung: Sehr niedrig Die veraltete Methode Redirect::home wurde entfernt. Leiten Sie stattdessen explizit auf eine benannte Route um.
// Vorher
return Redirect::home();

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

Testing

Service-Mocking

Auswirkung: Mittel Das veraltete Trait MocksApplicationServices wurde aus dem Framework entfernt. Es stellte Testmethoden wie expectsEvents, expectsJobs und expectsNotifications bereit. Wenn Sie diese Methoden verwenden, migrieren Sie zu Event::fake, Bus::fake bzw. Notification::fake.
// Vorher
$this->expectsEvents(OrderShipped::class);

// Nachher
Event::fake();
// ... Testcode ...
Event::assertDispatched(OrderShipped::class);

Validierung

Meldungen bei Closure-basierten Validierungsregeln

Auswirkung: Sehr niedrig Wenn Sie den $fail-Callback in einer Closure-basierten Custom-Rule mehrfach aufrufen, werden die Meldungen nicht mehr überschrieben, sondern in einem Array gesammelt. Der $fail-Callback gibt zudem nun ein Objekt zurück. Wenn Sie den Rückgabewert der Validierungsclosure typhinten, passen Sie das an.
public function rules()
{
    return [
        'name' => [
            function ($attribute, $value, $fail) {
                $fail('validation.translation.key')->translate();
            },
        ],
    ];
}

Methode after in FormRequests

Auswirkung: Sehr niedrig Die Methode after in FormRequests ist nun für Laravel reserviert. Wenn Sie in FormRequests eine after-Methode definieren, benennen Sie sie um oder nutzen Sie das neue „After-Validation”-Feature.

Fazit

Laravel 10 besteht aus vergleichsweise kleinen Änderungen; das Upgrade lässt sich zügig durchführen.
ÄnderungAuswirkungMaßnahme
Abhängigkeiten in composer.json aktualisierenHochAuf laravel/framework ^10.0 heben
PHP 8.1 / Composer 2.2 erforderlichHochVersionen prüfen und aktualisieren
Änderungen an Datenbank-ExpressionsMittel(string)-Cast durch getValue() ersetzen
Entfall der $dates-PropertyMittelAuf $casts migrieren
Monolog 3MittelBei Direktnutzung den Upgrade-Guide beachten
Redis-Cache-TagsMittelUmstieg auf Memcached prüfen
Entfall von MocksApplicationServicesMittelAuf Event::fake usw. migrieren
Entfall von Bus::dispatchNowNiedrigDurch Bus::dispatchSync ersetzen
ULID-SpaltennameNiedrigAufrufe von ulid() in Migrationen prüfen
Entfall von Redirect::homeSehr niedrigDurch Redirect::route('home') ersetzen

Referenzen

Zuletzt geändert am 13. Juli 2026