upgrade-laravel

Upgrade Laravel

When to use

• The user asks to upgrade Laravel, or the app is on Laravel 11 or older (see legacy/php-legacy).
• A fix exists only in Laravel 12 or 13 (for example the 2026 TokenGuard bypass and debug-page XSS).

For a minor or patch update within a major, run composer update laravel/framework --with-all-dependencies and Verify.

Before you start

• Read laravel/framework, PHP, and every Laravel-related package with its supported Laravel range: Livewire, Filament, Sanctum, Fortify, Horizon, Telescope, Cashier, Scout, Inertia, Spatie packages, and anything with a service provider.
• PHP minimum per target: Laravel 12 needs PHP 8.2+, Laravel 13 needs 8.3+. Run upgrade-php first if needed.
• Working tree clean; new branch (chore/laravel-13).
• Ask the user:
  • the target (default: 13, security support to 17 Mar 2028);
  • whether to stop for review after each major;
  • whether they want to use Laravel Shift (a paid service that opens an upgrade PR per major) instead of or alongside the manual steps;
  • whether network installs are approved (core/supply-chain cooldown applies).
• Plan the hops: one major at a time. Upgrade blockers (an abandoned package without support for the next major) must be resolved before that hop.

Steps

1. Baseline: composer install, php artisan test, PHPStan/Larastan, php artisan about, and a manual check of key flows. Record failures.
2. Patch the current major to its latest release and fix deprecation warnings in logs and tests.
3. Read the official upgrade guide for the next major (laravel.com/docs/<next>.x/upgrade) and list the items marked high and medium impact that apply to this app.
4. Update dependencies: in composer.json, set laravel/framework to the next major (^12.0), update first-party packages and dev tools (phpunit/phpunit, nunomaduro/collision, larastan/larastan) to the versions the guide lists, and third-party packages to versions that support it. Run composer update --with-all-dependencies and resolve conflicts by upgrading packages, not by --ignore-platform-reqs.
5. Optional Rector: composer require --dev driftingly/rector-laravel and run the matching set (LaravelSetList::LARAVEL_120, LARAVEL_130) with --dry-run first; review every change.
6. Apply the guide's code and config changes that Rector didn't, for example:
   • 10 → 11: PHP 8.2+, optional slim application structure (keep the existing structure unless asked), per-second rate limiting;
   • 11 → 12: PHP 8.2+, new starter kits (no need to change an existing app), dependency bumps;
   • 12 → 13: PHP 8.3+, the CSRF middleware renamed to PreventRequestForgery with Sec-Fetch-Site checks, and the other high-impact items in the guide. Check published config files against the framework's defaults for new options.
7. Packages with their own upgrade guides: follow them in the same hop (Livewire 2 → 3 → 4, Filament majors, Inertia, Horizon).
8. Verify (next section), show the diff and results, and wait for approval before the next hop. Commit only when asked (git-commit skill). At the target, switch to backend/laravel.