Einleitung
Laravel 13 wurde im März 2026 veröffentlicht. Dieser Leitfaden beschreibt die Upgrade-Schritte von Laravel 12.x auf 13.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.
KI-gestütztes Upgrade
Sie können das Upgrade auch mit Laravel Boost automatisieren. Boost ist ein First-Party-MCP-Server, der KI-Assistenten schrittweise Upgrade-Prompts bereitstellt. Nach der Installation in einer Laravel-12-Anwendung starten Sie in Claude Code, Cursor, OpenCode, Gemini oder VS Code das Upgrade über den Slash-Befehl/upgrade-laravel-v13. Der Befehl setzt laravel/boost ^2.0 voraus.
Auch KI-Tools ohne Slash-Command-Unterstützung können denselben Ablauf ausführen, wenn Sie die Prompt-Datei direkt referenzieren. Fügen Sie folgenden Prompt in Ihre KI ein.
Prompt
Änderungen nach Auswirkung
Auswirkung: Hoch
- Aktualisierung der Abhängigkeiten
- Aktualisierung des Laravel-Installers
- Request Forgery Prevention (CSRF)
Auswirkung: Mittel
- Cache-Einstellung
serializable_classes - Session-Einstellung
serialization
Auswirkung: Niedrig
- Cache-Präfix und Session-Cookie-Name
- Serialisierung von Model-Collections
Container::callund nullable Klassen-Defaults- Priorität registrierter Domain-Routen
- Exception-Payload im Event
JobAttempted - Binding von Manager-
extend-Callbacks - MySQL-
DELETE-Queries (JOIN / ORDER BY / LIMIT) - View-Namen der Bootstrap-Paginierung
- Benennung polymorpher Pivot-Tabellen
- Umbenennung von Properties im Event
QueueBusy - Reset der
Str-Factory zwischen Tests
Upgrade-Schritte
Abhängigkeiten aktualisieren
Auswirkung: Hoch Aktualisieren Sie incomposer.json folgende Abhängigkeiten.
Laravel-Installer aktualisieren
Auswirkung: Hoch Wenn Sie neue Laravel-Anwendungen mit dem Laravel-Installer-CLI erstellen, aktualisieren Sie diesen auf eine Version mit Laravel-13.x-Unterstützung. Wenn percomposer global require installiert:
Breaking Changes
Sicherheit
Request Forgery Prevention
Auswirkung: Hoch Die CSRF-Middleware in Laravel wurde vonVerifyCsrfToken in PreventRequestForgery umbenannt. Zusätzlich wurde die Prüfung der Anfrageherkunft über den Header Sec-Fetch-Site ergänzt.
VerifyCsrfToken und ValidateCsrfToken bleiben als deprecated Aliase erhalten; alle Direktreferenzen sollten Sie auf PreventRequestForgery umstellen. Achten Sie besonders auf Tests und Route-Definitionen, in denen die Middleware ausgeschlossen wird.
preventRequestForgery(...) verfügbar.
Cache
Cache-Präfix und Session-Cookie-Name
Auswirkung: Niedrig Die Default-Präfixe für Cache und Redis-Keys verwenden nun Bindestrich-getrennte Suffixe. Der Default-Session-Cookie-Name nutztStr::snake(...).
Die meisten Anwendungen setzen diese Werte in ihrer Konfigurationsdatei explizit und sind nicht betroffen. Nur Anwendungen, die sich auf die Framework-Fallbacks verlassen, sind es.
.env.
Cache-Einstellung serializable_classes
Auswirkung: Mittel
Der cache-Default-Konfiguration wurde serializable_classes mit dem Default false hinzugefügt. Damit werden PHP-Deserialisierungs-Gadget-Chain-Angriffe im Fall eines geleakten APP_KEY verhindert.
Wenn Ihre Anwendung PHP-Objekte im Cache ablegt, führen Sie die zu erlaubenden Klassen explizit auf.
Session-Einstellung serialization
Auswirkung: Mittel
Im Skeleton (laravel/laravel) von Laravel 13 ist in config/session.php 'serialization' => 'json' ergänzt. Der Framework-interne Default bleibt jedoch php.
Der offizielle Upgrade-Guide erwähnt diese Änderung nicht. Vermutlich ist damit gemeint, dass sie nicht zwingend übernommen werden muss. Bei Laravel-Upgrades von einer Version zur nächsten gibt es gelegentlich Änderungen, die keine Auswirkung haben und daher im Guide fehlen. Wenn man Jahre später upgradet und keine Information findet, wird es schwierig – deshalb sind inoffizielle Aufzeichnungen wertvoll.
Um das Verhalten wie in Laravel 12 zu erhalten, setzen Sie 'serialization' => 'php' explizit.
Container
Container::call und nullable Klassen-Defaults
Auswirkung: Niedrig
Container::call berücksichtigt nun die Default-Werte nullable Klassenparameter, wenn keine Bindung existiert (analog zum Verhalten für die Konstruktorinjektion aus Laravel 12).
Datenbank
MySQL-DELETE-Queries
Auswirkung: Niedrig
Laravel kompiliert im MySQL-Grammar nun vollständige DELETE ... JOIN-Queries inklusive ORDER BY und LIMIT.
In früheren Versionen konnten diese Klauseln bei DELETEs mit JOIN ignoriert werden. In Laravel 13 sind sie im generierten SQL enthalten. In Datenbank-Engines, die diese Syntax nicht unterstützen, kann es zu QueryException kommen.
Eloquent
Benennung polymorpher Pivot-Tabellen
Auswirkung: Niedrig Beim Ableiten des Tabellennamens für polymorphe Pivot-Modelle mit einer eigenen Pivot-Klasse erzeugt Laravel nun einen Pluralnamen. Wenn Sie sich auf den bisherigen Singular-Namen verlassen, setzen Sie den Tabellennamen im Pivot-Modell explizit.Serialisierung von Model-Collections
Auswirkung: Niedrig Beim Serialisieren und Wiederherstellen von Eloquent-Model-Collections (etwa bei in Queues gespeicherten Jobs) werden nun eager-geladene Relationen wieder an die Modelle gehängt. Code, der sich auf das Fehlen dieser Relationen nach der Deserialisierung verlässt, benötigt Anpassungen.Queue
Exception-Payload im Event JobAttempted
Auswirkung: Niedrig
Das Event Illuminate\Queue\Events\JobAttempted gibt nun statt einer boolean-Property $exceptionOccurred das Exception-Objekt (oder null) über $exception frei.
Umbenennung von Properties im Event QueueBusy
Auswirkung: Niedrig
Die Property $connection des Events Illuminate\Queue\Events\QueueBusy wurde zur Vereinheitlichung mit anderen Queue-Events in $connectionName umbenannt.
Routing
Priorität registrierter Domain-Routen
Auswirkung: Niedrig Routen mit expliziter Domain haben beim Matching nun Vorrang vor Routen ohne Domain. Damit funktionieren Catch-All-Subdomain-Routen konsistent, auch wenn zuvor eine Nicht-Domain-Route registriert wurde.Support
Binding von Manager-extend-Callbacks
Auswirkung: Niedrig
Über extend registrierte Custom-Driver-Closures eines Managers werden nun an die Manager-Instanz gebunden.
Wenn in diesen Callbacks bisher $this auf ein anderes Objekt zeigte (etwa den Service Provider), verschieben Sie den Wert per use (...) in den Closure-Scope.
Reset der Str-Factory zwischen Tests
Auswirkung: Niedrig
Laravel setzt beim Test-Teardown Custom Str-Factories zurück.
Wenn Sie sich darauf verlassen haben, dass eine benutzerdefinierte UUID-/ULID-/Random-String-Factory über Testmethoden hinweg bestehen bleibt, konfigurieren Sie sie in jedem betreffenden Test oder Setup-Hook.
Views
View-Namen der Bootstrap-Paginierung
Auswirkung: Niedrig Die internen Paginierungs-View-Namen für Bootstrap 3 wurden explizit gemacht.Deprecated Features
| Feature | Alternative |
|---|---|
Middleware VerifyCsrfToken | PreventRequestForgery |
Middleware ValidateCsrfToken | PreventRequestForgery |
JobAttempted::$exceptionOccurred | JobAttempted::$exception |
QueueBusy::$connection | QueueBusy::$connectionName |
Ergänzungen bei den Contracts
Auswirkung: Sehr niedrig Nur relevant, wenn Sie eigene Implementierungen der Contracts pflegen.Contract Dispatcher
Der Contract Illuminate\Contracts\Bus\Dispatcher erhielt die Methode dispatchAfterResponse($command, $handler = null).
Contract ResponseFactory
Der Contract Illuminate\Contracts\Routing\ResponseFactory erhielt die Signatur eventStream.
Contract MustVerifyEmail
Der Contract Illuminate\Contracts\Auth\MustVerifyEmail erhielt die Methode markEmailAsUnverified().
Contract Queue
Der Contract Illuminate\Contracts\Queue\Queue erhielt folgende Methoden zur Größenprüfung der Queue (zuvor nur im DocBlock deklariert).
pendingSizedelayedSizereservedSizecreationTimeOfOldestPendingJob
Contracts Store / Repository
An den Cache-Contracts wurde die Methode touch zur TTL-Verlängerung ergänzt.
Highlights neuer Features
KI-gestütztes Upgrade (Laravel Boost)
Laravel Boost ist der offizielle MCP-Server. In Verbindung mit KI-Editoren automatisieren Sie das Upgrade teilweise über/upgrade-laravel-v13.
Origin-Prüfung per Sec-Fetch-Site
Die Middleware PreventRequestForgery prüft zusätzlich per Sec-Fetch-Site den Origin und stärkt damit den CSRF-Schutz.
Sichere Cache-Deserialisierung
Überserializable_classes werden nur zugelassene Klassen deserialisiert. Die Sicherheit gegen PHP-Deserialisierungsangriffe verbessert sich.
eventStream für SSE (Server-Sent Events)
Der Contract ResponseFactory erhält eventStream; die SSE-Unterstützung wurde verbessert.
Bessere Sichtbarkeit von Queues
MitpendingSize, delayedSize, reservedSize u. a. am Queue-Contract lassen sich Queue-Zustände granularer beobachten.
Häufige Migrationsprobleme und Lösungen
Problem: CSRF-Tests schlagen fehl
Symptom: Tests, dieVerifyCsrfToken referenzieren, schlagen mit „Klasse nicht gefunden” fehl.
Lösung: Alle Referenzen auf PreventRequestForgery umstellen.
Problem: Cache liefert keine Objekte zurück
Symptom: Aus dem Cache gelesene Daten sindnull oder es wird eine UnserializationFailedException geworfen.
Lösung: Ergänzen Sie die verwendeten Klassen in config/cache.php unter serializable_classes oder wandeln Sie die zwischengespeicherten Werte in Arrays um.
Problem: JobAttempted-Listener funktioniert nicht
Symptom: $event->exceptionOccurred ist null oder undefiniert.
Lösung: Auf $event->exception !== null umstellen.
Problem: Session wird ungültig
Symptom: Nach dem Upgrade werden Nutzer ausgeloggt. Lösung: Der Default-Session-Cookie-Name hat sich geändert. Setzen Sie in.env SESSION_COOKIE explizit auf den bisherigen Wert.
Problem: Cache-Keys werden nicht gefunden
Symptom: Nach dem Upgrade steigt die Zahl der Cache-Misses. Lösung: Das Cache-Präfix hat sich geändert. Setzen SieCACHE_PREFIX in .env oder leeren Sie den Cache.
Referenzen
- Offizieller Upgrade-Guide (Englisch)
- Diff im Repository laravel/laravel (12.x → 13.x)
- Laravel Shift – Community-Dienst zur Upgrade-Automatisierung
- Laravel Boost – MCP-Server für KI-gestützte Upgrades