# Laravel v12 Migration Guide — Lessons Learned

> This document is a consolidated reference compiled from individual AI-assisted migration sessions. Its purpose is to give any future AI (or human) a head start by documenting what went wrong, why, and how it was resolved.

## How to Use This Document

- **For AI assistants:** Read this before attempting any Laravel v12 or related package upgrades. The issues listed here are real, observed problems — not hypothetical.
- **For humans:** Use the table of contents to jump to relevant sections.

---

## Table of Contents

- [[#Package Upgrade Issues]]
- [[#Breaking Changes in Laravel v12]]
- [[#Breaking Changes in Third-Party Packages]]
- [[#Configuration & Environment Issues]]
- [[#Database & Migration Issues]]
- [[#Testing Issues]]
- [[#Miscellaneous Gotchas]]

---

## Package Upgrade Issues

<!-- Add entries in the format below -->
<!-- ### Package Name (old version → new version)
**Problem:** Description of what went wrong.
**Root Cause:** Why it happened.
**Fix:** What resolved it.
**Source Log:** [[Logs/YYYY-MM-DD-session-name]] -->

---

## Breaking Changes in Laravel v12

<!-- Documented breaking changes encountered during migration -->

---

## Breaking Changes in Third-Party Packages

<!-- Non-Laravel packages that broke during upgrade -->

---

## Configuration & Environment Issues

<!-- Config files, .env changes, service provider registration, etc. -->

---

## Database & Migration Issues

<!-- Schema changes, migration order problems, seeder failures, etc. -->

---

## Testing Issues

<!-- Test suite failures, mock incompatibilities, factory changes, etc. -->

---

## Miscellaneous Gotchas

<!-- Anything that doesn't fit neatly into the above categories -->

---

## Source Logs

Individual session logs are stored in the [[Logs/]] subdirectory. Each log represents one AI session's raw notes. This combined guide extracts and organizes the actionable content from those logs.

---

*Last updated: 2026-02-11*