/laravel-upgrade-v13

name: laravel-upgrade-v13
description: Use when upgrading a Laravel 12 application to Laravel 13.0 — composer bump, breaking changes, and Attributes migration.
versions:
  laravel: "13.0"
  php: "8.3"
user-invocable: true
references: references/composer-upgrade.md, references/breaking-changes.md, references/attributes-migration.md, references/laravel-boost-mcp.md, references/checklist.md, references/templates/composer.json.md, references/templates/upgrade-script.sh.md
related-skills: laravel-architecture, laravel-eloquent, laravel-queues, laravel-attributes, laravel-auth, laravel-testing, solid-php

<objective> Covers the full Laravel 12 → 13.0 upgrade path: the PHP 8.3 minimum requirement, composer commands to bump Laravel/PHPUnit 12/Pest 4/Tinker, mandatory breaking changes (VerifyCsrfToken → PreventRequestForgery, cache prefix hyphens, serializable_classes hardening, pheanstalk 7.x/8.x for Beanstalkd, Symfony 7.4/8.0 support), the optional Eloquent + Queue Attributes migration, and the Laravel Boost MCP automated `/upgrade-laravel-v13` path. Provides a phased checklist (pre-upgrade audit → composer bump → breaking-change fixes → attributes migration → validation). </objective>

Laravel 12 → 13 Upgrade Guide

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

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](references/composer-upgrade.md) for exact commands.

---

Reference Guide

| Topic | Reference | When to consult | |-------|-----------|-----------------| | **Composer commands** | [composer-upgrade.md](references/composer-upgrade.md) | Bump dependencies | | **Breaking changes** | [breaking-changes.md](references/breaking-changes.md) | Fix L13 mandatory updates | | **Attributes migration** | [attributes-migration.md](references/attributes-migration.md) | Modernize Eloquent/Queue classes | | **Laravel Boost MCP** | [laravel-boost-mcp.md](references/laravel-boost-mcp.md) | Automated `/upgrade-laravel-v13` | | **Checklist** | [checklist.md](references/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](references/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](references/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](references/breaking-changes.md#3-cache-prefixes-hyphenated).

---

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