laravel-upgrade-v13

Laravel 12 → 13 Upgrade Guide

Centralized upgrade path from Laravel 12.x (latest 12.69) to Laravel 13 (13.0 released March 17, 2026; current stable 13.33).

Agent Workflow (MANDATORY)

Before ANY upgrade, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase — Audit current Laravel 12 patterns ($fillable, $tries, VerifyCsrfToken references)
2. fuse-ai-pilot:research-expert — Verify latest Laravel 13 docs via Context7 (/laravel/docs/13.x/upgrade)
3. fuse-laravel:laravel-expert — Apply Laravel 13 best practices

After upgrade, run fuse-ai-pilot:sniper for validation.

---

Overview

Phase	Goal	Effort
1. Pre-upgrade audit	Detect L12 patterns in codebase	30 min
2. Composer bump	Update Laravel + PHPUnit + Pest + Tinker	5 min
3. Breaking changes fixes	Apply mandatory L13 changes	1-3 h
4. Attributes migration	Eloquent + Queue properties → Attributes (optional)	2-4 h
5. Validation	Tests pass, CI green	30 min

Most projects: < 1 day total.

---

Critical Rules

1. PHP 8.3 minimum — Drop PHP 8.2 support before upgrading composer.
2. PHPUnit 12 + Pest 4 (official upgrade target) — bump dev dependencies first to catch test failures early. Pest 5 / PHPUnit 13 are available later but require PHP 8.4+.
3. VerifyCsrfToken → PreventRequestForgery — rename middleware references in bootstrap/app.php and aliases.
4. Cache prefix breaking change — hyphens replace underscores by default. Set CACHE_PREFIX, REDIS_PREFIX, SESSION_COOKIE to preserve old behavior if cache invalidation is unacceptable.
5. Never mix Attributes + properties on the same Eloquent/Queue class — pick one source of truth per model/job.

---

Architecture

upgrade-path/
├── 1-composer/        # bump dependencies
├── 2-breaking-fixes/  # mandatory changes
├── 3-attributes/      # optional refactor to Attributes
└── 4-validation/      # tests + sniper

→ See composer-upgrade.md for exact commands.

---

Reference Guide

Topic	Reference	When to consult
Composer commands	composer-upgrade.md	Bump dependencies
Breaking changes	breaking-changes.md	Fix L13 mandatory updates
Attributes migration	attributes-migration.md	Modernize Eloquent/Queue classes
Laravel Boost MCP	laravel-boost-mcp.md	Automated /upgrade-laravel-v13
Checklist	checklist.md	Step-by-step validation

---

Quick Reference

Composer bump (5 min)

composer require laravel/framework:^13.0 laravel/tinker:^3.0
composer require --dev phpunit/phpunit:^12.0 pestphp/pest:^4.0
composer update

→ See composer-upgrade.md for full sequence.

Breaking change: PreventRequestForgery

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->preventRequestForgery(except: [
        'stripe/*',
        'webhook/*',
    ]);
})

→ See breaking-changes.md for all 12 changes.

Cache prefix migration

# .env — preserve L12 underscore behavior
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session

→ See breaking-changes.md.

---

Best Practices

DO

• Bump PHPUnit + Pest FIRST so failing tests appear before refactor
• Run upgrade on a feature branch (feat/laravel-13-upgrade)
• Use Laravel Boost MCP /upgrade-laravel-v13 for guided automation
• Test in staging with real cache + queue workers before prod
• Keep properties + Attributes migration as a SEPARATE PR (not bundled with breaking fixes)

DON'T

• ❌ Skip the cache prefix env vars if you have warm caches in prod
• ❌ Upgrade composer directly on main without CI verification
• ❌ Mix #[Fillable] and $fillable on the same model
• ❌ Forget pda/pheanstalk: ^8.0 (or ^7.0) if you use Beanstalkd
• ❌ Leave nested model instantiation (new static()) inside a model's boot() / trait boot*() — throws LogicException in L13