Vincent/Obsidian-Vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add upgrade log for HGBI migration from Laravel 11 to 12

Browse Source
This commit is contained in:
Vincent Verbruggen
2026-02-24 08:10:57 +01:00
parent 42faa22564
commit 600b236019
2 changed files with 387 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

314
Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-hgbi.md Normal file
View File

@@ -0,0 +1,314 @@
# Update Log: HGBI — Laravel 11 → 12 + Ecosystem
> **Date:** 2026-02-20
> **Branch:** `updates-to-v12`
> **AI Tool:** Claude Code (Opus 4.6)
---
## Starting State
| Package | Before | Target |
|-------------------|---------|----------------------|
| PHP | 8.4.17 | (no change expected) |
| laravel/framework | 11.48.0 | ^12.0 |
| filament/filament | 3.3.49 | ^5.0 |
| livewire/livewire | 3.7.10 | ^4.0 (via Filament) |
| tailwindcss | 3.4.19 | ^4.0 |
| pestphp/pest | 4.x | (no change expected) |
**Baseline tests:** 249 passed (1774 assertions), 3 risky, 20 incomplete
**Baseline build:** Success (client + SSR)
---
## Upgrade Phases
### Phase 1: Pre-Flight
- [x] Branch created (`updates-to-v12`)
- [x] Baseline tests recorded
- [x] Baseline build verified
- [x] Reference document consulted
### Phase 2: Composer — Remove Blockers
- [x] `codezero/laravel-localizer` removed
- [x] `codezero/laravel-localized-routes` replaced with `opgginc/codezero-laravel-localized-routes:^5.0`
- [x] `codezero/composer-preload-files` set to `false` in allow-plugins
- [x] `saloonphp/laravel-http-sender` removed, `config/saloon.php` updated to `GuzzleSender`
- [x] `johncarter/filament-focal-point-picker` removed and usage cleaned from 2 files
- [x] Bootstrap cache cleared
- [x] Tests pass (249), build succeeds
### Phase 3: Composer — Laravel 12 + Direct Dependencies
- [x] Laravel framework 12.52.0 installed
- [x] All direct dependencies bumped (see Packages Changed table)
- [x] `spatie/icalendar-generator` v3 enum syntax fixed (`EventStatus::Confirmed`, `Classification::Private`)
- [x] Bootstrap cache cleared
- [x] Tests pass (249), build succeeds
### Phase 4: Filament v3 → v5
- [x] `filament/spatie-laravel-translatable-plugin` removed (no v4/v5 exists)
- [x] Filament v5.2.2 installed directly (v4 intermediary had no translatable support)
- [x] `filament/upgrade:^4.0` installed, `filament-v4` rector run on `app/`
- [x] `filament/upgrade:^5.0` installed, `filament-v5` rector run on `app/`
- [x] `lara-zeus/spatie-translatable:^2.0` installed (replaces translatable plugin)
- [x] `DisplayText::make()` signature fixed (`?string $name = null`)
- [x] `TextInput\Mask` replaced in `ShippingRateResource` and `CouponResource`
- [x] `FaqsRelationManager` form signature fixed (`Schema $schema`)
- [x] Livewire v4.1.4 installed (via Filament)
- [x] Tests pass (249), build succeeds
### Phase 5: NPM Major Updates
- [x] Major frontend packages upgraded
- [x] vite.config.js SSR fix: `@inertiajs/server` → `@inertiajs/vue3`
- [x] `@vue/server-renderer` deduplicated (removed from dependencies, kept in devDependencies)
- [x] `apexcharts` added as explicit dependency (previously transitive)
- [x] Build succeeds (client + SSR)
- [x] Tests pass (249)
### Phase 6: ESLint Cleanup
- [x] `eslint-plugin-tailwindcss` removed from devDeps and eslint.config.mjs
- [x] Tailwind-specific rules/settings cleaned from ESLint config
- [x] Linter passes
### Phase 7: Final Verification (Laravel 12 Upgrade)
- [x] Tests pass: 249 passed (1774 assertions), 3 risky, 20 incomplete — matches baseline
- [x] Build succeeds (client + SSR)
- [x] Pint passes (`--dirty --format agent` → `pass`)
- [x] `composer outdated --direct` → all up to date
- [x] `npm outdated` → only deferred packages (eslint 10, tailwindcss 4, globals 17)
- [x] `php artisan about` → Laravel 12.52.0
### Phase 8: Tailwind CSS v3 → v4
- [x] Automated upgrade tool (`@tailwindcss/upgrade`) run — partially succeeded
- Migrated `app.css` directives (`@import 'tailwindcss'`, `@config` reference, border compat layer)
- Updated `tailwindcss` package to ^4.2.0
- Failed on: callback-based theme extensions (`negative`), then `tailwindcss/defaultTheme` module removed in v4
- [x] Manual fixes applied:
- Callback theme extensions (`inset: (theme, {negative}) => ...`) converted to static `...generateSpacing()` objects
- `tailwindcss/defaultTheme` import removed, font stack inlined
- `@tailwindcss/postcss` installed, `postcss.config.js` updated (removed `autoprefixer`)
- `@layer base` → `@utility` blocks in `utility.css` (13 utilities converted)
- Custom-class-in-custom-class patterns expanded (`inner-container`/`container`/`outer-container` no longer
`@apply pl-container pr-container`)
- Container override: `@source not inline('container')` added to `app.css` (ref #37)
- `corePlugins.container = false` removed from JS config (not supported in v4 CSS-first mode)
- Old TW v3 plugins removed: `@tailwindcss/forms`, `@tailwindcss/typography`, `@tailwindcss/aspect-ratio`,
`autoprefixer`
- `require()` plugin calls removed from `tailwind.config.js` (forms/typography now built into v4)
- `@formkit/themes/tailwindcss` plugin kept — works in compat mode
- [x] Deprecated TW v3 class patterns updated in 4 Vue files:
- `bg-gray-500 bg-opacity-75` → `bg-gray-500/75` (3 modal components)
- `ring-black ring-opacity-5` → `ring-black/5` (1 component)
- [x] Build succeeds (client + SSR)
- [x] Tests pass: 249 passed (1774 assertions) — matches baseline
- [x] Filament assets republished (`php artisan filament:upgrade --no-interaction`)
### Phase 9: Final Verification
- [x] Tests pass: 249 passed (1774 assertions), 3 risky, 20 incomplete — matches baseline
- [x] Build succeeds (client + SSR)
- [x] `npm outdated` → only deferred packages (eslint 10, globals 17)
---
## Exceptions & Issues
### Issue 1: Saloon HttpSender config broke after removing laravel-http-sender
**Symptom:** 17 test failures in Labonovum/Saloon-related tests after removing `saloonphp/laravel-http-sender`.
**Root Cause:** `config/saloon.php` referenced `Saloon\HttpSender\HttpSender` which was in the removed package. Then
changed to `Saloon\Laravel\HttpSender` which also doesn't exist in v3.
**Fix:** Changed to `Saloon\Http\Senders\GuzzleSender` (the default in `saloonphp/laravel-plugin` v3).
**Files affected:** `config/saloon.php`
### Issue 2: spatie/icalendar-generator v3 enum method syntax changed
**Symptom:** `Call to undefined method Spatie\IcalendarGenerator\Enums\EventStatus::confirmed()`
**Root Cause:** v3 switched from method-based enums to PHP 8.1 backed enums (`::Confirmed` instead of `::confirmed()`).
**Fix:** `EventStatus::confirmed()` → `EventStatus::Confirmed`, `Classification::private()` → `Classification::Private`
**Files affected:** `provider/Models/Appointment.php`
### Issue 3: filament/spatie-laravel-translatable-plugin has no v4 or v5
**Symptom:** No v4/v5 release exists. Plugin only has v3.x which requires `filament/support:self.version` (v3), blocking
Filament upgrade.
**Root Cause:** The translatable plugin was deprecated by Filament and replaced by a community package.
**Fix:** Removed `filament/spatie-laravel-translatable-plugin`, installed `lara-zeus/spatie-translatable:^2.0`. Rector
scripts automatically migrated all 40+ imports.
**Files affected:** All Filament resource files using translatable traits.
### Issue 4: ariaieboy/filament-currency v3 requires Filament v5
**Symptom:** `ariaieboy/filament-currency:^3` requires `filament/tables ^5.0`, blocking Filament v4 installation.
**Root Cause:** v3.0.0 skipped v4 support entirely.
**Fix:** Went directly to Filament v5, installed `ariaieboy/filament-currency:^3`.
### Issue 5: DisplayText::make() signature incompatibility
**Symptom:**
`Declaration of App\Forms\Components\DisplayText::make(string $name = ''): static must be compatible with Filament\Forms\Components\Field::make(?string $name = null): static`
**Root Cause:** Filament v4+ changed `Field::make()` from `string $name` to `?string $name = null` (ref #17).
**Fix:** Updated to `make(?string $name = null)` and pass `$name ?? ''` to parent.
**Files affected:** `app/Forms/Components/DisplayText.php`
### Issue 6: TextInput\Mask removed in Filament v5
**Symptom:** `use Filament\Forms\Components\TextInput\Mask` import fails.
**Root Cause:** Mask builder class removed in Filament v5 (ref #15).
**Fix:** Replaced mask closures with `->numeric()->step(0.01)->minValue(0)->prefix('€')` approach.
**Files affected:** `app/Filament/Resources/ShippingRateResource.php`, `app/Filament/Resources/CouponResource.php`
### Issue 7: Missing apexcharts npm dependency
**Symptom:** `Rollup failed to resolve import "apexcharts"` during build.
**Root Cause:** `vue3-apexcharts` requires `apexcharts` as peer dep, previously resolved transitively (ref #51).
**Fix:** Added `apexcharts` as explicit dependency.
**Files affected:** `package.json`
### Issue 8: Tailwind upgrade tool fails on callback-based theme extensions
**Symptom:** `Cannot destructure property 'negative' of 'undefined'`
**Root Cause:** `tailwind.config.js` used callback functions for theme extensions (e.g.,
`inset: (theme, {negative}) => ...`).
TW v4's upgrade tool cannot evaluate these.
**Fix:** Converted all callback-based theme extensions to static objects using `...generateSpacing()`.
**Files affected:** `tailwind.config.js`
### Issue 9: `tailwindcss/defaultTheme` module removed in TW v4
**Symptom:** `Cannot find module 'tailwindcss/defaultTheme'` during upgrade tool template migration step.
**Root Cause:** TW v4 removed the `defaultTheme` export. The config imported it for `fontFamily.sans` fallback stack.
**Fix:** Removed the import, inlined the default sans font stack directly.
**Files affected:** `tailwind.config.js`
### Issue 10: Custom `.container` class overridden by TW v4 built-in
**Symptom:** Potential layout breakage — TW v4 generates its own `.container` utility that would override the project's
custom one.
**Root Cause:** `corePlugins.container = false` from JS config is not supported in TW v4 CSS-first mode (ref #37).
**Fix:** Added `@source not inline('container')` and `@source not inline('container!')` to `app.css`.
**Files affected:** `resources/css/app.css`
### Issue 11: `@layer base` with `@apply` fails in TW v4
**Symptom:** `Cannot apply unknown utility class` when building.
**Root Cause:** TW v4 no longer supports `@apply` inside `@layer base` for custom utility classes (ref #35).
**Fix:** Converted all `@layer base` custom utilities to `@utility` blocks. Non-`@apply` styles (`.hide-scrollbar`,
`.lds-ellipsis`, etc.) moved to plain CSS.
**Files affected:** `resources/css/utility.css`
---
## Packages Changed
| Package | From | To | Notes |
|------------------------------------------------|---------|---------|---------------------------------------|
| `laravel/framework` | 11.48.0 | 12.52.0 | Core upgrade |
| `filament/filament` | 3.3.49 | 5.2.2 | Skipped v4 (no translatable) |
| `livewire/livewire` | 3.7.10 | 4.1.4 | Via Filament |
| `barryvdh/laravel-debugbar` | 3.16.5 | 4.0.9 | Clean |
| `darkaonline/l5-swagger` | 9.0.1 | 10.1.0 | Clean |
| `mollie/laravel-mollie` | 3.1.0 | 4.0.2 | Clean |
| `predis/predis` | 2.4.1 | 3.4.0 | Clean |
| `spatie/eloquent-sortable` | 4.5.2 | 5.0.0 | Clean |
| `spatie/calendar-links` | 1.11.1 | 2.0 | Not used in code |
| `spatie/icalendar-generator` | 2.9.2 | 3.2.1 | Enum syntax change |
| `laravel-notification-channels/fcm` | 4.5.0 | 6.0.1 | Skipped v5 |
| `muhammadhuzaifa/telescope-guzzle-watcher` | 3.2.2 | 4.0.0 | Clean |
| `staudenmeir/belongs-to-through` | 2.16.4 | 2.17 | Clean |
| `staudenmeir/eloquent-has-many-deep` | 1.20.x | 1.21 | Clean |
| `amidesfahani/filament-tinyeditor` | 3.x | 4.x | Clean |
| `ariaieboy/filament-currency` | 1.x | 3.0.0 | Clean |
| `ralphjsmit/laravel-filament-components` | 2.x | 3.x | Clean |
| `filament/spatie-laravel-media-library-plugin` | 3.3.49 | 5.2.2 | Clean |
| `filament/spatie-laravel-settings-plugin` | 3.3.49 | 5.2.2 | Clean |
| `codezero/laravel-localized-routes` | 4.0.1 | — | Removed |
| `codezero/laravel-localizer` | 3.0.0 | — | Removed |
| `saloonphp/laravel-http-sender` | 3.1.0 | — | Removed (abandoned) |
| `johncarter/filament-focal-point-picker` | 3.1.0 | — | Removed |
| `filament/spatie-laravel-translatable-plugin` | 3.3.49 | — | Removed |
| `opgginc/codezero-laravel-localized-routes` | — | 5.1.0 | Added (fork) |
| `lara-zeus/spatie-translatable` | — | 2.0.0 | Added (replaces translatable plugin) |
| `laravel-vite-plugin` | 1.3.0 | 2.1.0 | Requires Vite 7 |
| `vite` | 6.4.1 | 7.3.1 | Required by laravel-vite-plugin |
| `@vitejs/plugin-vue` | 5.2.4 | 6.0.4 | Required by Vite 7 |
| `@vueuse/core` | 13.9.0 | 14.2.1 | Clean |
| `@vueuse/integrations` | 13.9.0 | 14.2.1 | Clean |
| `vue-i18n` | 9.14.5 | 11.2.8 | Clean |
| `uuid` | 11.1.0 | 13.0.0 | Clean |
| `vue-number-animation` | 1.1.2 | 2.0.2 | Needs `--legacy-peer-deps` |
| `imagetools-core` | 7.1.0 | 9.1.0 | Clean |
| `vite-imagetools` | 7.1.1 | 9.0.3 | Clean |
| `rollup-plugin-visualizer` | 5.14.0 | 6.0.5 | Clean |
| `eslint-plugin-tailwindcss` | 3.18.0 | — | Removed |
| `apexcharts` | — | 5.6.0 | Added (was transitive) |
| `tailwindcss` | 3.4.19 | 4.2.0 | CSS-first mode with `@config` compat |
| `@tailwindcss/postcss` | — | 0.1.3 | Added (replaces `tailwindcss` plugin) |
| `@tailwindcss/forms` | 0.5.4 | — | Removed (built into v4) |
| `@tailwindcss/typography` | 0.5.9 | — | Removed (built into v4) |
| `@tailwindcss/aspect-ratio` | 0.4.2 | — | Removed (built into v4) |
| `autoprefixer` | 10.4.14 | — | Removed (built into v4) |
---
## What Worked Without Issues
- `darkaonline/l5-swagger` 9 → 10: no code changes
- `mollie/laravel-mollie` 3 → 4: no code changes
- `spatie/eloquent-sortable` 4 → 5: no code changes
- `predis/predis` 2 → 3: no code changes
- `barryvdh/laravel-debugbar` 3 → 4: only bootstrap cache clear needed
- `staudenmeir/belongs-to-through` and `eloquent-has-many-deep`: patch bumps, clean
- All Filament companion plugins (media-library, settings, tinyeditor, currency, components): clean upgrades
- `@vueuse/core` and `@vueuse/integrations` 13 → 14: no breaking changes encountered
- `vue-i18n` 9 → 11: no import changes needed
- `uuid` 11 → 13: no changes needed
- Filament rector scripts (v4 + v5): handled most namespace transforms correctly
- `lara-zeus/spatie-translatable:^2.0`: drop-in replacement, rector migrated all imports
- `@formkit/themes/tailwindcss` plugin: works in TW v4 compat mode via `@config` without changes
---
## Remaining / Unresolved
- **ESLint v9 → v10**: Intentionally deferred (+ globals 16 → 17).
- **`vue-number-animation` peer dep conflict**: Installed with `--legacy-peer-deps`. The v2 package has an optional peer
dep on `@vue/composition-api` which conflicts with Vue 3. Works correctly at runtime.
- **npm audit vulnerabilities**: 15 high, 1 moderate — review separately.
- **Tailwind v4 visual validation**: Build succeeds but manual visual validation is required. TW v4 changes CSS output
in subtle ways that automated tests cannot detect. Open key pages in browser and compare against pre-upgrade state.
- **`tailwind.config.js` still uses JS compat mode**: The project uses `@config` in CSS to load the JS config. A future
cleanup could migrate everything to pure CSS-first `@theme {}` blocks, but this is not required and the compat mode
works correctly.
---
## Miscellaneous
- Tailwind CSS v3 → v4 completed in Phase 8. Uses `@config` compat mode (JS config still present).
- ESLint v9 → v10 is not in scope.
- Filament v4 step was effectively skipped due to translatable plugin incompatibility. Went v3 → v5 directly, but ran
both v4 and v5 rector scripts.
- The `post-update-cmd` script in `composer.json` runs `filament:upgrade` automatically on every
`composer update/require`, which generates large diffs in `public/js/filament/*` and `public/css/filament/*`.
- `spatie/calendar-links` upgraded to v2 but is not referenced anywhere in code (might be removable).
---
## Recommendations for Next Session
- **Manual visual validation** of key pages (homepage, product pages, Filament admin, provider dashboard, modals).
TW v4 changes CSS output subtly — a green build does not guarantee correct layout.
- Consider removing `spatie/calendar-links` if truly unused.
- Review and address npm audit vulnerabilities.
- Consider migrating `tailwind.config.js` to pure CSS-first `@theme {}` blocks (optional, compat mode works fine).
- ESLint v10 upgrade when ready.