vault backup: 2026-02-11 09:22:03
This commit is contained in:
Vincent Verbruggen
@@ -0,0 +1,77 @@
|
||||
# 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*
|
||||
43
Work/Projects/Laravel-v12-Migration/Logs/TEMPLATE.md
Normal file
43
Work/Projects/Laravel-v12-Migration/Logs/TEMPLATE.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Migration Session Log
|
||||
|
||||
> Copy this template for each AI session. Name the file `YYYY-MM-DD-short-description.md`.
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**AI Tool:** (e.g., Claude Code, Cursor, Copilot, ChatGPT)
|
||||
**Project/Repo:**
|
||||
**Scope:** (e.g., "Upgrade Laravel 11 → 12", "Update Spatie packages", "Fix test suite after upgrade")
|
||||
|
||||
---
|
||||
|
||||
## What Was Attempted
|
||||
|
||||
-
|
||||
|
||||
## What Went Wrong
|
||||
|
||||
### Issue 1: Title
|
||||
**Symptom:** What you observed (error message, failing test, broken behavior).
|
||||
**Root Cause:** Why it happened (breaking change, deprecated API, version conflict).
|
||||
**Fix Applied:** What resolved it.
|
||||
**Time Wasted:** (optional) Rough estimate of how long this blocked progress.
|
||||
|
||||
### Issue 2: Title
|
||||
<!-- Repeat as needed -->
|
||||
|
||||
## What Worked Without Issues
|
||||
|
||||
-
|
||||
|
||||
## Packages Changed
|
||||
|
||||
| Package | From | To | Notes |
|
||||
|---------|------|----|-------|
|
||||
| | | | |
|
||||
|
||||
## Remaining / Unresolved
|
||||
|
||||
-
|
||||
|
||||
## Recommendations for Next Session
|
||||
|
||||
-
|
||||
117
Work/Projects/Laravel-v12-Migration/update-deversspecialist.md
Normal file
117
Work/Projects/Laravel-v12-Migration/update-deversspecialist.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# Upgrade Log: Laravel 11 → 12 + Full Ecosystem
|
||||
|
||||
## Starting State
|
||||
|
||||
| Package | Before | Target |
|
||||
| -------------------------------- | ------- | ------ |
|
||||
| laravel/framework | 11.48.0 | ^12.0 |
|
||||
| filament/filament | 3.3.48 | ^5.0 |
|
||||
| livewire/livewire | 3.7.10 | ^4.0 |
|
||||
| tailwindcss | 3.4.19 | ^4.0 |
|
||||
| pestphp/pest | 3.8.5 | ^4.0 |
|
||||
| barryvdh/laravel-debugbar | 3.16.5 | ^4.0 |
|
||||
| jeffgreco13/filament-breezy | 2.6.4 | ^3.0 |
|
||||
| ariaieboy/filament-currency | 1.13.0 | ^3.0 |
|
||||
| amidesfahani/filament-tinyeditor | 3.0.0 | ^4.0 |
|
||||
| mollie/laravel-mollie | 3.1.0 | ^4.0 |
|
||||
|
||||
**Baseline tests:** 14 passed (41 assertions)
|
||||
**Baseline build:** Success (client + SSR)
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Pre-Flight
|
||||
|
||||
- [x] Branch created: `upgrade/laravel-12-full`
|
||||
- [x] Baseline tests: 14 passed
|
||||
- [x] Baseline build: success
|
||||
|
||||
## Phase 2: Composer — Laravel 12
|
||||
|
||||
- [x] Replaced `codezero/laravel-localized-routes` with `opgginc/codezero-laravel-localized-routes:^5.0` (drop-in fork)
|
||||
- [x] Removed `codezero/laravel-localizer` (single-locale nl project)
|
||||
- [x] Set `codezero/composer-preload-files` to `false` in allow-plugins (transitive dep still present)
|
||||
- [x] Updated constraints: laravel/framework ^12, symfony/http-client ^8.0, symfony/mailgun-mailer ^8.0, barryvdh/laravel-debugbar ^4.0, mollie/laravel-mollie ^4.0
|
||||
- [x] `composer update -W` — Laravel v12.50.0 installed
|
||||
- [x] Tests: 14 passed
|
||||
|
||||
## Phase 3: Filament v3 → v4 → v5
|
||||
|
||||
- [x] Removed `awcodes/filament-table-repeater` (no Filament v4/v5 version exists)
|
||||
- [x] Replaced TableRepeater with standard `Filament\Forms\Components\Repeater` in ChildrenRelationManager
|
||||
- [x] Ran `filament-v4` rector on 197 files
|
||||
- [x] Removed `filament/spatie-laravel-translatable-plugin` (no v4 release), skipped to v5
|
||||
- [x] Ran `filament-v5` rector on 197 files
|
||||
- [x] Installed all Filament v5 packages + `lara-zeus/spatie-translatable:^2.0`
|
||||
- [x] Fixed ~20 files: `Filament\Pages\Actions\*` → `Filament\Actions\*`
|
||||
- [x] Fixed `Filament\Forms\Set` → `Filament\Schemas\Components\Utilities\Set` (ProductResource, ChildrenRelationManager)
|
||||
- [x] Filament v5.2.1, Livewire v4.1.4 installed
|
||||
- [x] Tests: 14 passed
|
||||
|
||||
## Phase 4: Tailwind v3 → v4
|
||||
|
||||
- [x] Installed tailwindcss@^4, @tailwindcss/postcss, @tailwindcss/cli
|
||||
- [x] Removed autoprefixer, @tailwindcss/forms, @tailwindcss/typography, @tailwindcss/aspect-ratio, eslint-plugin-tailwindcss
|
||||
- [x] Updated postcss.config.js to use @tailwindcss/postcss
|
||||
- [x] Migrated tailwind.config.js to CSS-first config in app.css (@theme, @source, @variant directives)
|
||||
- [x] Converted utility.css from @layer to @utility directives
|
||||
- [x] Deleted tailwind.config.js
|
||||
- [x] Removed tailwindcss settings from eslint.config.mjs
|
||||
- [x] Installed vite@^7, @vitejs/plugin-vue@^6, laravel-vite-plugin@^2
|
||||
- [x] Build: success, Tests: 14 passed
|
||||
|
||||
## Phase 5: Pest v3 → v4
|
||||
|
||||
- [x] Upgraded pestphp/pest:^4.0 + pestphp/pest-plugin-laravel:^4.0
|
||||
- [x] Pest v4.3.2, PHPUnit 12.5.8 installed
|
||||
- [x] Tests: 14 passed
|
||||
|
||||
## Phase 6: NPM Updates
|
||||
|
||||
- [x] Removed eslint-plugin-tailwindcss (re-added by quality:update, incompatible with TW v4)
|
||||
- [x] Fixed eslint.config.mjs (removed tailwindcss settings block re-added by quality:update)
|
||||
- [x] `npm update` for minor/patch bumps
|
||||
- [x] Major updates: @vuepic/vue-datepicker ^12.1.0, @vueuse/core ^14.2.1, swiper ^12.1.0, vite-imagetools ^9.0.2, imagetools-core ^9.1.0, vite-plugin-vue-devtools ^8.0.6, vue-flatpickr-component ^12.0.0, globals ^17.3.0
|
||||
- [x] Fixed `VueDatePicker` import: default → named export (v12 breaking change)
|
||||
- [x] ESLint stays at v9 (intentionally skipped)
|
||||
- [x] Build: success
|
||||
|
||||
## Phase 7: Final Verification
|
||||
|
||||
- [x] Tests: 14 passed (41 assertions)
|
||||
- [x] Build: success (client + SSR)
|
||||
- [x] Pint: clean (fixed 2 lang files)
|
||||
- [x] `composer outdated --direct`: only predis/predis v2→v3 (out of scope)
|
||||
- [x] `npm outdated`: only eslint v9→v10, @eslint/js v9→v10 (intentionally skipped)
|
||||
- [x] `php artisan filament:upgrade`: assets published successfully
|
||||
- [x] `php artisan about`: Laravel 12.50.0 confirmed
|
||||
|
||||
---
|
||||
|
||||
## Final State
|
||||
|
||||
| Package | Version |
|
||||
| ------------------- | ------- |
|
||||
| laravel/framework | 12.50.0 |
|
||||
| filament/filament | 5.2.1 |
|
||||
| livewire/livewire | 4.1.4 |
|
||||
| tailwindcss | 4.x |
|
||||
| pestphp/pest | 4.3.2 |
|
||||
| phpunit/phpunit | 12.5.8 |
|
||||
| vite | 7.3.1 |
|
||||
| @vitejs/plugin-vue | 6.x |
|
||||
| laravel-vite-plugin | 2.x |
|
||||
|
||||
---
|
||||
|
||||
## Exceptions & Issues Log
|
||||
|
||||
1. **codezero/composer-preload-files plugin error**: After removing codezero packages, `composer dump-autoload` failed. Fix: set `allow-plugins.codezero/composer-preload-files` to `false`.
|
||||
2. **awcodes/filament-table-repeater blocks Filament v4**: No compatible version. Fix: removed package, replaced with standard Repeater.
|
||||
3. **lara-zeus/spatie-translatable requires Filament v5**: Rector changed imports to LaraZeus namespace during v4 step, but package wasn't installable until v5. Caused transient FatalError. Fix: skip translatable during v4, install with v5.
|
||||
4. **filament-v5 rector MissingInputException**: Running without input fails. Fix: pipe `echo "app"` to rector.
|
||||
5. **Vite 7 peer dependency conflicts**: laravel-vite-plugin@^2 requires Vite 7. Fix: install vite@^7 with `--force`.
|
||||
6. **@import must precede @source in TW v4**: CSS ordering constraint. Fix: move @import before @source directives.
|
||||
7. **eslint-plugin-tailwindcss re-added by quality:update**: `strixi/laravel-quality` re-publishes eslint.config.mjs on `composer update`. Fix: remove the package and tailwindcss settings again after composer operations.
|
||||
8. **@vuepic/vue-datepicker v12 default export removed**: Changed to named export. Fix: `import { VueDatePicker }` instead of default import.
|
||||
9. **Add basic browser smoke tests after upgrade**: After completing the upgrade, set up `pestphp/pest-plugin-browser` + Playwright and create browser tests that seed pages (via `PageSeeder`) and visit key public routes (`/`, `/over-ons`, `/contact`). Use `assertNoSmoke()` to catch JS errors and console logs. This catches runtime issues (broken Inertia renders, missing assets, JS import errors) that unit/feature tests won't find.
|
||||
Reference in New Issue
Block a user