Add upgrade log for HGBI migration from Laravel 11 to 12
This commit is contained in:
Vincent Verbruggen
@@ -1,6 +1,6 @@
|
||||
# Laravel 12 Migration: Problems & Solutions Reference
|
||||
|
||||
> Compiled from 5 real project migrations (Contentmakers, QLS Handling, Deversspecialist, Cleanshopping, Goos).
|
||||
> Compiled from 6 real project migrations (Contentmakers, QLS Handling, Deversspecialist, Cleanshopping, Goos, HGBI).
|
||||
> Intended audience: an AI assistant performing the next Laravel 12 upgrade, or a human developer doing it manually.
|
||||
|
||||
---
|
||||
@@ -69,7 +69,7 @@ composer dump-autoload
|
||||
|
||||
**Rule**: Do this after every major Composer operation (package removal, replacement, or major version upgrade).
|
||||
|
||||
**Projects affected**: All 5 projects.
|
||||
**Projects affected**: All 6 projects.
|
||||
|
||||
---
|
||||
|
||||
@@ -104,7 +104,7 @@ composer dump-autoload
|
||||
- Remove `codezero/laravel-localizer` entirely (typically unused — verify `use_localizer` is `false` in config, or that no PHP code references `CodeZero\Localizer`).
|
||||
- Set `codezero/composer-preload-files` to `false` in `allow-plugins`.
|
||||
|
||||
**Projects affected**: All 5 projects.
|
||||
**Projects affected**: All 6 projects.
|
||||
|
||||
### 5. codezero/composer-preload-files blocks Composer after removal
|
||||
|
||||
@@ -138,7 +138,25 @@ composer dump-autoload
|
||||
|
||||
**Projects affected**: Contentmakers.
|
||||
|
||||
### 9. Composer `post-update-cmd` scripts can trigger Filament upgrade side effects
|
||||
### 9. `saloonphp/laravel-http-sender` removal breaks Saloon config
|
||||
|
||||
**Problem**: After removing the abandoned `saloonphp/laravel-http-sender` package, tests fail because `config/saloon.php` still references `Saloon\HttpSender\HttpSender` (from the removed package) or `Saloon\Laravel\HttpSender` (which does not exist in v3).
|
||||
|
||||
**Fix**: Change `config/saloon.php` sender class to `Saloon\Http\Senders\GuzzleSender` (the default in `saloonphp/laravel-plugin` v3).
|
||||
|
||||
**Projects affected**: HGBI.
|
||||
|
||||
### 10. `spatie/icalendar-generator` v3 enum syntax change
|
||||
|
||||
**Problem**: `Call to undefined method Spatie\IcalendarGenerator\Enums\EventStatus::confirmed()`. v3 switched from method-based enums to PHP 8.1 backed enums.
|
||||
|
||||
**Fix**: Change method calls to enum case access:
|
||||
- `EventStatus::confirmed()` → `EventStatus::Confirmed`
|
||||
- `Classification::private()` → `Classification::Private`
|
||||
|
||||
**Projects affected**: HGBI.
|
||||
|
||||
### 11. Composer `post-update-cmd` scripts can trigger Filament upgrade side effects
|
||||
|
||||
**Problem**: Running `composer require` or `composer update` triggers `php artisan filament:upgrade` via `post-update-cmd`, republishing Filament assets and creating large git diffs.
|
||||
|
||||
@@ -146,7 +164,7 @@ composer dump-autoload
|
||||
|
||||
**Rule**: On upgrade branches, assume Composer package changes may create large Filament asset diffs.
|
||||
|
||||
**Projects affected**: Contentmakers.
|
||||
**Projects affected**: Contentmakers, HGBI.
|
||||
|
||||
---
|
||||
|
||||
@@ -182,6 +200,8 @@ composer dump-autoload
|
||||
|
||||
> **You cannot skip v4.** Filament must be upgraded v3 → v4 → v5 in sequence. Each step has its own rector script (`vendor/bin/filament-v4`, `vendor/bin/filament-v5`). Running the v5 rector on a v3 codebase will produce incorrect or incomplete results. The v4 rector must run first and the v4 packages must be installed before proceeding to v5.
|
||||
|
||||
> **Republish Filament assets if they were published.** Many projects have published Filament assets (CSS, JS, fonts) to `public/css/filament/`, `public/js/filament/`, and `public/fonts/filament/`. After completing the Filament upgrade, run `php artisan filament:upgrade --no-interaction` to republish these assets for v5. If you skip this, the admin panel may load with broken or missing styles/scripts. This command also clears config, route, and view caches. Expect a large git diff from the republished assets — commit them separately.
|
||||
|
||||
### 13. Rector scripts require explicit directory input
|
||||
|
||||
**Problem**: `vendor/bin/filament-v4` and `vendor/bin/filament-v5` require interactive input (directory prompt). Running without input causes `MissingInputException`.
|
||||
@@ -234,9 +254,9 @@ The rector/codemod tools do not catch everything. The following require manual f
|
||||
|
||||
**Problem**: Legacy closures typed as `Forms\Components\TextInput\Mask` are invalid in Filament v5.
|
||||
|
||||
**Fix**: Replace with v5-safe numeric/step/prefix configuration. Grep for `TextInput\Mask` and rewrite.
|
||||
**Fix**: Replace with v5-safe numeric/step/prefix configuration (e.g., `->numeric()->step(0.01)->minValue(0)->prefix('€')`). Grep for `TextInput\Mask` and rewrite.
|
||||
|
||||
**Projects affected**: Contentmakers.
|
||||
**Projects affected**: Contentmakers, HGBI.
|
||||
|
||||
### 16. Filament v5 `Component::$container` uninitialized error
|
||||
|
||||
@@ -254,7 +274,7 @@ The rector/codemod tools do not catch everything. The following require manual f
|
||||
|
||||
**Fix**: Change to `make(?string $name = null)` and pass `$name ?? ''` to parent.
|
||||
|
||||
**Projects affected**: Goos.
|
||||
**Projects affected**: Goos, HGBI.
|
||||
|
||||
### 18. `ViewAction` on ListRecords pages crashes in v5
|
||||
|
||||
@@ -302,7 +322,7 @@ Several third-party Filament plugins do not support v4 or v5:
|
||||
|
||||
**Note**: `lara-zeus/spatie-translatable` requires Filament v5 (not v4). If upgrading v3→v4→v5, skip translatable during the v4 step and install with v5.
|
||||
|
||||
**Projects affected**: Deversspecialist, Goos.
|
||||
**Projects affected**: Deversspecialist, Goos, HGBI.
|
||||
|
||||
### 23. Post-codemod verification scan
|
||||
|
||||
@@ -403,7 +423,9 @@ Remove deprecated config keys from `config/passport.php`:
|
||||
|
||||
## Tailwind CSS v3 → v4
|
||||
|
||||
> **Important**: Tailwind v3 → v4 should be treated as a separate upgrade step, not bundled into a single pass with other changes. The migration touches CSS architecture (PostCSS config, utility directives, theme tokens, custom classes) and frequently produces visual regressions that are invisible to automated tests. A developer must manually check the frontend after migration — open key pages in a browser and compare against the pre-upgrade state. Do not consider this step complete based on `npm run build` succeeding alone; a green build does not mean the layout is correct.
|
||||
> **This must be its own separate step.** Do not bundle Tailwind v4 into a single pass with other upgrades. The migration touches CSS architecture (PostCSS config, utility directives, theme tokens, custom classes) and frequently produces visual regressions that are invisible to automated tests. A developer must manually check the frontend after migration — open key pages in a browser and compare against the pre-upgrade state. Do not consider this step complete based on `npm run build` succeeding alone; a green build does not mean the layout is correct.
|
||||
>
|
||||
> **Always try the official upgrade tool first (`npx @tailwindcss/upgrade`).** Even when it fails (and it often does — see #33), it still saves significant work by migrating directives, class syntax, and config structure. The effort spent fixing blockers to get the tool to run is almost always less than doing the entire migration manually. The workflow is: run the tool → fix whatever it chokes on → run it again → repeat until it succeeds → then do the manual cleanup for anything it missed.
|
||||
|
||||
### 33. Automated upgrade tool (`@tailwindcss/upgrade`) often fails
|
||||
|
||||
@@ -421,7 +443,7 @@ Remove deprecated config keys from `config/passport.php`:
|
||||
4. Run with `--force` on upgrade branches
|
||||
5. Unpack custom-class-in-custom-class patterns to raw utilities before running
|
||||
|
||||
**Projects affected**: Contentmakers, Deversspecialist, Goos.
|
||||
**Projects affected**: Contentmakers, Deversspecialist, Goos, HGBI.
|
||||
|
||||
### 34. PostCSS plugin package split
|
||||
|
||||
@@ -437,7 +459,7 @@ module.exports = { plugins: { '@tailwindcss/postcss': {} } }
|
||||
|
||||
Remove `autoprefixer` package (no longer needed).
|
||||
|
||||
**Projects affected**: All projects.
|
||||
**Projects affected**: All 6 projects.
|
||||
|
||||
### 35. `@layer base` → `@utility` for custom utility classes
|
||||
|
||||
@@ -445,7 +467,7 @@ Remove `autoprefixer` package (no longer needed).
|
||||
|
||||
**Fix**: Convert to `@utility` blocks instead of `@layer base`. Expand any custom-class-in-custom-class usage to raw utility classes.
|
||||
|
||||
**Projects affected**: Contentmakers, Deversspecialist, Goos.
|
||||
**Projects affected**: Contentmakers, Deversspecialist, Goos, HGBI.
|
||||
|
||||
### 36. `@import` must precede all other statements
|
||||
|
||||
@@ -467,7 +489,7 @@ Remove `autoprefixer` package (no longer needed).
|
||||
|
||||
**Verification**: Built CSS should contain only the custom `.container` rule.
|
||||
|
||||
**Projects affected**: Contentmakers.
|
||||
**Projects affected**: Contentmakers, HGBI.
|
||||
|
||||
### 38. Remove stale `tailwind.config.js` after migration
|
||||
|
||||
@@ -503,9 +525,29 @@ These plugins no longer exist as separate packages in Tailwind v4:
|
||||
|
||||
Remove them from `devDependencies`. Use `--force` if `npm uninstall` fails with peer dependency conflicts.
|
||||
|
||||
**Projects affected**: All projects.
|
||||
**Projects affected**: All 6 projects.
|
||||
|
||||
### 41. `eslint-plugin-tailwindcss` is not Tailwind v4 compatible
|
||||
### 41. `tailwindcss/defaultTheme` module removed in TW v4
|
||||
|
||||
**Problem**: `Cannot find module 'tailwindcss/defaultTheme'` during upgrade tool or build. Config files that import `defaultTheme` for font family fallback stacks break.
|
||||
|
||||
**Fix**: Remove the import and inline the default font stack directly in the config.
|
||||
|
||||
**Projects affected**: HGBI.
|
||||
|
||||
### 42. Deprecated TW v3 opacity class patterns
|
||||
|
||||
**Problem**: TW v3 patterns like `bg-gray-500 bg-opacity-75` and `ring-black ring-opacity-5` are deprecated in v4. They still work but generate warnings and may break in future versions.
|
||||
|
||||
**Fix**: Replace with modern slash syntax:
|
||||
- `bg-gray-500 bg-opacity-75` → `bg-gray-500/75`
|
||||
- `ring-black ring-opacity-5` → `ring-black/5`
|
||||
|
||||
Grep for `opacity-` in Vue/Blade templates to find all instances.
|
||||
|
||||
**Projects affected**: HGBI.
|
||||
|
||||
### 43. `eslint-plugin-tailwindcss` is not Tailwind v4 compatible
|
||||
|
||||
**Problem**: Linting fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` for `tailwindcss/resolveConfig`. The plugin requires `tailwindcss ^3.4.0`.
|
||||
|
||||
@@ -513,7 +555,7 @@ Remove them from `devDependencies`. Use `--force` if `npm uninstall` fails with
|
||||
|
||||
**Watch out**: If using `strixi/laravel-quality` or similar packages, they may re-add `eslint-plugin-tailwindcss` config on `composer update`. Remove again after Composer operations.
|
||||
|
||||
**Projects affected**: All projects.
|
||||
**Projects affected**: All 6 projects.
|
||||
|
||||
---
|
||||
|
||||
@@ -603,17 +645,17 @@ Remove them from `devDependencies`. Use `--force` if `npm uninstall` fails with
|
||||
|
||||
**Fix**: Upgrade `vite` to `^7.0.0`. May need `--force` flag.
|
||||
|
||||
**Projects affected**: Deversspecialist, Goos.
|
||||
**Projects affected**: Deversspecialist, Goos, HGBI.
|
||||
|
||||
### 51. Clean npm install can expose missing direct dependencies
|
||||
|
||||
**Problem**: After lock regeneration, Vite build fails resolving packages (e.g., `lodash`) that were previously available transitively.
|
||||
**Problem**: After lock regeneration, Vite build fails resolving packages (e.g., `lodash`, `apexcharts`) that were previously available transitively.
|
||||
|
||||
**Fix**: Add missing packages as explicit direct dependencies.
|
||||
|
||||
**Rule**: After lock regeneration, treat unresolved imports as missing direct dependency declarations.
|
||||
|
||||
**Projects affected**: Contentmakers.
|
||||
**Projects affected**: Contentmakers, HGBI.
|
||||
|
||||
### 52. Duplicate npm dependency entries
|
||||
|
||||
@@ -651,7 +693,7 @@ Additionally:
|
||||
|
||||
**Fix**: Change `ssr.noExternal` from `['@inertiajs/server']` to `['@inertiajs/vue3']` in `vite.config.js`.
|
||||
|
||||
**Projects affected**: Goos.
|
||||
**Projects affected**: Goos, HGBI.
|
||||
|
||||
---
|
||||
|
||||
@@ -773,6 +815,15 @@ These packages upgraded without issues across multiple projects. No special hand
|
||||
| `filament/spatie-laravel-tags-plugin` | 3 → 5 | No code changes |
|
||||
| `nunomaduro/collision` | 7 → 8 | No code changes |
|
||||
| `laravel/sanctum` | 3 → 4 | No code changes |
|
||||
| `predis/predis` | 2 → 3 | No code changes |
|
||||
| `muhammadhuzaifa/telescope-guzzle-watcher` | 3 → 4 | No code changes |
|
||||
| `staudenmeir/belongs-to-through` | 2.16 → 2.17 | No code changes |
|
||||
| `staudenmeir/eloquent-has-many-deep` | 1.20 → 1.21 | No code changes |
|
||||
| `laravel-notification-channels/fcm` | 4 → 6 | No code changes (skipped v5) |
|
||||
| `rollup-plugin-visualizer` | 5 → 6 | No code changes |
|
||||
| `@vueuse/core` | 13 → 14 | No code changes |
|
||||
| `vue-i18n` | 9 → 11 | No code changes |
|
||||
| `uuid` (npm) | 11 → 13 | No code changes |
|
||||
|
||||
---
|
||||
|
||||
@@ -785,6 +836,7 @@ These packages upgraded without issues across multiple projects. No special hand
|
||||
| Deversspecialist | `Logs/upgrade-log-deversspecialist.md`, `Logs/upgrade-log-deversspecialist-composer.md` |
|
||||
| Cleanshopping | `Logs/upgrade-log-cleanshopping.md` |
|
||||
| Goos | `Logs/upgrade-log-goos.md` |
|
||||
| HGBI | `Logs/upgrade-log-hgbi.md` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user