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

Add upgrade logs for Laravel 11 to 12 migration across multiple projects

Browse Source 
- Created detailed upgrade log for deversspecialist with phases including Composer updates, Filament upgrades, Tailwind migration, Pest updates, and final verification.
- Added upgrade log for goos project, documenting version changes, encountered issues, and resolutions during the migration process.
- Documented Composer dependency upgrades for qlshandling, highlighting significant changes and necessary code adjustments.
- Introduced a template for future upgrade logs to standardize documentation for Laravel migrations.
This commit is contained in:
Vincent Verbruggen
2026-02-20 10:43:24 +01:00
parent a8fdd403b1
commit 1999dbbc11
10 changed files with 1061 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
Work/Projects/Laravel-v12-Migration/Combined-Migration-Guide.md
View File

@@ -1,77 +0,0 @@
# 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*

791
Work/Projects/Laravel-v12-Migration/Laravel-12-Migration-Problems-and-Solutions.md Normal file
View File

@@ -0,0 +1,791 @@
# Laravel 12 Migration: Problems & Solutions Reference
> Compiled from 5 real project migrations (Contentmakers, QLS Handling, Deversspecialist, Cleanshopping, Goos).
> Intended audience: an AI assistant performing the next Laravel 12 upgrade, or a human developer doing it manually.
---
## How to Use This Document
Read this before starting any Laravel 11 → 12 migration. Every item below is a real, observed problem — not hypothetical. The document is organized by upgrade area. Each entry follows the pattern:
- **Problem**: what went wrong
- **Root Cause**: why it happened
- **Fix**: what resolved it
- **Projects affected**: which projects hit this issue
---
## Prompt for AI Assistants
Before starting, place these two files in the project root (or provide them in the conversation context):
1. This reference document (`Laravel-12-Migration-Problems-and-Solutions.md`)
2. The update log template (`Logs/TEMPLATE.md`) — use it as the structure for the new project's update log
Copy-paste this prompt when starting a new project migration with an AI assistant:
> Hi, we are going to update to the next version of Laravel and update everything that goes along with it. So please run `composer outdated`. Gather all the resources you need to do the updates and then make a plan.
>
> There is a file "Laravel 12 Migration: Problems & Solutions Reference.md" — it contains all the errors and weirdness we have encountered in previous updates. Take these things into account if relevant for this project. And make an update log yourself (use the TEMPLATE.md as the structure) so we can later add that to the document for any other projects that need updating.
>
> Then when the Composer work has been done, do `npm outdated` and do the same thing. Gather all the resources, make a plan, and keep track of all the exceptions and log anything out of the ordinary in the same markdown file.
>
> If anything is unclear, use the AskUserQuestion skill. When in doubt, ask. Ask about approach, preferences, naming, styling, scope — anything. Multiple questions per interaction are encouraged. Do not assume — confirm with the user first.
---
## Table of Contents
1. [[#Pre-Flight / Preparation]]
2. [[#Composer & Package Resolution]]
3. [[#Laravel 12 Breaking Changes]]
4. [[#Filament v3 → v5]]
5. [[#Livewire v3 → v4]]
6. [[#Laravel Passport 12 → 13]]
7. [[#Tailwind CSS v3 → v4]]
8. [[#PHPUnit & Pest Upgrades]]
9. [[#ESLint Migration]]
10. [[#NPM / Frontend Build]]
11. [[#Inertia v1 → v2]]
12. [[#Browser Testing]]
13. [[#Post-Upgrade Verification Checklist]]
14. [[#Recommended Upgrade Order]]
---
## Pre-Flight / Preparation
### 1. Always clear bootstrap cache after major package changes
**Problem**: After removing, replacing, or upgrading packages, `php artisan` commands fail with `Class ... ServiceProvider not found` errors. Examples: `Barryvdh\Debugbar\ServiceProvider`, `CodeZero\Localizer\LocalizerServiceProvider`, `Filament\Upgrade\UpgradeServiceProvider`.
**Root Cause**: Stale `bootstrap/cache/packages.php` and `bootstrap/cache/services.php` retain references to old/removed service providers.
**Fix**: Delete both files and re-run discovery:
```bash
rm -f bootstrap/cache/packages.php bootstrap/cache/services.php
composer dump-autoload
```
**Rule**: Do this after every major Composer operation (package removal, replacement, or major version upgrade).
**Projects affected**: All 5 projects.
---
### 2. Composer cache path issues in sandboxed environments
**Problem**: `composer outdated` fails with `Cannot create cache directory`.
**Fix**: Run with `COMPOSER_CACHE_DIR=/tmp/composer-cache composer outdated`.
**Projects affected**: Deversspecialist.
---
### 3. Record baseline test count before starting
**Problem**: After PHPUnit major upgrades, test counts can silently drop (e.g., 14 → 3) because test discovery rules changed. Without knowing the baseline, this goes unnoticed.
**Rule**: Before any upgrade work, record the exact test count and assertion count. After each upgrade phase, verify the count has not dropped.
**Projects affected**: Contentmakers, Goos.
---
## Composer & Package Resolution
### 4. codezero packages block Laravel 12
**Problem**: `codezero/laravel-localized-routes` (^4), `codezero/laravel-localizer` (^3), and `codezero/laravel-uri-translator` (^2) all hard-require `illuminate/support ^10.0|^11.0`. No stable release supports Laravel 12.
**Fix**:
- Replace `codezero/laravel-localized-routes` with `opgginc/codezero-laravel-localized-routes:^5.0` (maintained fork, same `CodeZero\LocalizedRoutes` namespace, drop-in replacement).
- 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.
### 5. codezero/composer-preload-files blocks Composer after removal
**Problem**: After removing codezero packages, the `composer-preload-files` plugin still exists in vendor as a transitive dependency. Composer refuses to run any command.
**Fix**: `composer config --no-plugins allow-plugins.codezero/composer-preload-files false`
**Projects affected**: Goos, Deversspecialist.
### 6. Localized routes: `/en/` prefix no longer generated after fork switch
**Problem**: After switching to `opgginc/codezero-laravel-localized-routes ^5`, English locale redirects lose their `/en/` prefix (e.g., `/ds` instead of `/en/ds`), even when `omitted_locale` is set to `nl`.
**Status**: Open / needs investigation per project. May be a config difference in the v5 fork.
**Projects affected**: Goos.
### 7. resend/resend-laravel must move to ^1.0 for Laravel 12
**Problem**: `resend/resend-laravel ^0.14` or `^0.23` only supports Illuminate 10/11.
**Fix**: Upgrade to `resend/resend-laravel ^1.0`. No API changes encountered in practice.
**Projects affected**: Contentmakers, Deversspecialist.
### 8. laravel-lang packages need major version bump
**Problem**: `laravel-lang/lang:^12` and `laravel-lang/common:^3` are anchored to a publisher line that only supports Illuminate <=11.
**Fix**: Move to newer major lines compatible with Laravel 12 (check latest available versions at upgrade time).
**Projects affected**: Contentmakers.
### 9. 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.
**Fix**: Treat as expected side effect. Group Filament public-asset changes and commit separately.
**Rule**: On upgrade branches, assume Composer package changes may create large Filament asset diffs.
**Projects affected**: Contentmakers.
---
## Laravel 12 Breaking Changes
### 10. HasUuids generates UUID v7 instead of v4
**Problem**: `HasUuids` trait now generates UUID v7 by default. This can break tests or code that expects UUID v4 format.
**Fix**: Use `use HasVersion4Uuids as HasUuids;` in affected models (e.g., `Attachment`, `JobApplication`).
**Projects affected**: Deversspecialist.
### 11. `image` validation rule excludes SVGs
**Problem**: The `image` validation rule no longer accepts SVG files in Laravel 12.
**Status**: Not encountered in practice across any project, but worth monitoring during testing.
### 12. `route:list` can throw due to controller-constructor abort guards
**Problem**: `php artisan route:list --path=admin` fails with `NotFoundHttpException` because the command instantiates controllers during route metadata collection, and some controllers have `abort_unless(...)` in their constructor.
**Fix**: Use `php artisan about` + tests/build for smoke checks instead. Long-term: move hard feature gates out of constructors into middleware.
**Rule**: Avoid `abort_*` calls in controller constructors.
**Projects affected**: Contentmakers.
---
## Filament v3 → v5
> **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.
### 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`.
**Fix**: Pipe input: `echo "app" | vendor/bin/filament-v4` and `echo "modules" | vendor/bin/filament-v4`. Run for EACH custom namespace directory separately: `app/`, `cms/`, `commerce/`, `modules/`, `support/`, etc.
**Rule**: Always enumerate all custom source roots before running Filament codemods.
**Projects affected**: All projects with Filament.
### 14. Rector scripts miss certain transformations
The rector/codemod tools do not catch everything. The following require manual fixes:
#### a. `Filament\Pages\Actions\*` → `Filament\Actions\*`
**Problem**: Old action imports remain after rector.
**Fix**: Grep for `use Filament\Pages\Actions;` and replace all matches with `use Filament\Actions;`.
**Projects affected**: Contentmakers, Deversspecialist, Goos.
#### b. `Filament\Forms\Set|Get` → `Filament\Schemas\Components\Utilities\Set|Get`
**Fix**: Search and replace across all Filament resource files.
**Projects affected**: Contentmakers, Deversspecialist.
#### c. Form/Schema layout components moved to `Filament\Schemas\...`
**Problem**: Layout/utility classes moved namespaces but rector didn't update all imports.
**Fix**: Migrate these imports:
| Old | New |
|-----|-----|
| `Filament\Forms\Components\Fieldset` | `Filament\Schemas\Components\Fieldset` |
| `Filament\Forms\Components\Grid` | `Filament\Schemas\Components\Grid` |
| `Filament\Forms\Components\Section` | `Filament\Schemas\Components\Section` |
| `Filament\Forms\Components\Tabs\Tab` | `Filament\Schemas\Components\Tabs\Tab` |
| `Filament\Forms\Components\Component` | `Filament\Schemas\Components\Component` |
| `Filament\Forms\Get` | `Filament\Schemas\Components\Utilities\Get` |
| `Filament\Forms\Set` | `Filament\Schemas\Components\Utilities\Set` |
**Projects affected**: Contentmakers.
#### d. `form(Form $form): Form` → `form(Schema $schema): Schema`
**Problem**: Partial codemod application leaves old signatures in some resources/relation managers.
**Fix**: Grep for `use Filament\Forms\Form;` and remove all remaining occurrences. Update method signatures.
**Projects affected**: Contentmakers.
#### e. `$navigationGroup` and `$navigationIcon` type changes (Filament v4)
**Problem**: `protected static ?string $navigationGroup` must be `protected static string | \UnitEnum | null $navigationGroup`. Same for `$navigationIcon` → `string | \BackedEnum | null`. Rector does NOT catch this.
**Fix**: Search for `protected static ?string $navigationGroup` and `$navigationIcon` and update types manually. Not needed if the project uses method overrides instead of static properties.
**Projects affected**: Deversspecialist.
### 15. `TextInput\Mask` builder class removed
**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.
**Projects affected**: Contentmakers.
### 16. Filament v5 `Component::$container` uninitialized error
**Problem**: `Typed property Filament\Schemas\Components\Component::$container must not be accessed before initialization` — thrown when calling `getChildComponents()` on Filament form components outside a Livewire context (e.g., during frontend page rendering via CMS Block systems).
**Root Cause**: Filament v5's `getChildComponents()` creates a `Schema` wrapper that requires `getLivewire()`, which fails outside Filament admin panel context.
**Fix**: Replace `getChildComponents()` with `getDefaultChildComponents()` which returns raw component arrays without requiring a Schema/Livewire container. In `hasSettings()` methods, use the safe `getSchemaChildComponents()` resolver and treat closure schemas as non-resolvable (`false`).
**Projects affected**: Contentmakers, Goos.
### 17. `Field::make()` signature change
**Problem**: `make(string $name)` changed to `make(?string $name = null)`. Any subclass overriding `make()` with `string $name = ''` must update.
**Fix**: Change to `make(?string $name = null)` and pass `$name ?? ''` to parent.
**Projects affected**: Goos.
### 18. `ViewAction` on ListRecords pages crashes in v5
**Problem**: `ViewAction::make()` in `getHeaderActions()` on a list page causes `getViewAuthorizationResponse(): Argument #1 ($record) must be of type Model, null given`.
**Root Cause**: In v5, `ViewAction` tries to authorize against a record, but list pages have no record.
**Fix**: Replace `ViewAction::make()` with `Action::make('name')` for navigation-only header actions.
**Projects affected**: Goos.
### 19. Filament v5 evaluates column labels during initialization
**Problem**: `$livewire->tableFilters` is `null` before filters are populated, causing "Trying to access array offset on null" errors when accessed in column labels/formatters.
**Fix**: Use null-safe access with `?? null` or `?? 'default'` defaults when accessing filter values in column labels.
**Projects affected**: Deversspecialist.
### 20. `filament:upgrade` creates large public asset diffs
**Problem**: `php artisan filament:upgrade --no-interaction` republishes many files under `public/js/filament/*`, `public/css/filament/*`, and `public/fonts/filament/*`.
**Fix**: Run once per upgrade pass, review/commit asset churn separately. Do not run repeatedly.
**Projects affected**: Contentmakers, Deversspecialist.
### 21. Filament v5 rector can print Rector cache deletion errors but still exit successfully
**Problem**: Commands report `Unable to delete ... rector_cached_files ... No such file or directory` but finish with success messaging.
**Fix**: Do not trust command success text alone. Run a post-codemod class-import existence scan and targeted runtime smoke checks.
**Projects affected**: Contentmakers.
### 22. Incompatible Filament plugins
Several third-party Filament plugins do not support v4 or v5:
| Plugin | Issue | Fix |
|--------|-------|-----|
| `awcodes/filament-table-repeater` | No v4/v5 version | Replace with standard `Filament\Forms\Components\Repeater` |
| `johncarter/filament-focal-point-picker` | Only supports `^3.0\|^4.0` | Remove, replace with `TextInput` storing coordinates as string |
| `filament/spatie-laravel-translatable-plugin` | Deprecated in v4, no v5 | Replace with `lara-zeus/spatie-translatable:^2.0` |
**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.
### 23. Post-codemod verification scan
After running all rector/codemod scripts, run these verification commands:
```bash
# Check for old Filament namespace imports that rector missed
grep -r "use Filament\\Pages\\Actions;" app/ cms/ commerce/ modules/ support/
grep -r "use Filament\\Forms\\Form;" app/ cms/ commerce/ modules/ support/
grep -r "use Filament\\Forms\\Components\\Fieldset;" app/ cms/ commerce/ modules/ support/
grep -r "use Filament\\Forms\\Get;" app/ cms/ commerce/ modules/ support/
grep -r "use Filament\\Forms\\Set;" app/ cms/ commerce/ modules/ support/
grep -r "TextInput\\Mask" app/ cms/ commerce/ modules/ support/
grep -r "protected static ?string \$navigationGroup" app/ cms/ commerce/ modules/ support/
```
---
## Livewire v3 → v4
### 24. Config key renames
| Old Key | New Key |
|---------|---------|
| `layout` | `component_layout` |
| `lazy_placeholder` | `component_placeholder` |
**Projects affected**: QLS Handling.
### 25. `wire:model` behavior unchanged (deferred by default)
`wire:model` without `.live` works the same in both v3 and v4 (deferred by default). No action needed.
### 26. Potential gotchas (not encountered but worth knowing)
- `wire:model.blur` / `.change` behavior changed: in v4, these modifiers now control client-side state sync timing too. Add `.live` before them for old behavior: `wire:model.live.blur`.
- Component tags must be closed: unclosed `<livewire:component>` tags are interpreted as slot content in v4.
- `@livewireStyles`/`@livewireScripts`: still work with `inject_assets => true`.
---
## Laravel Passport 12 → 13
### 27. `Passport::hashClientSecrets()` removed
Secrets are always hashed in v13. Remove all calls to `Passport::hashClientSecrets()`.
**Projects affected**: QLS Handling.
### 28. Middleware renamed
| Old | New |
|-----|-----|
| `CheckClientCredentials` | `CheckToken` |
| `CheckClientCredentialsForAnyScope` | `CheckTokenForAnyScope` |
| `CheckScopes` | `CheckToken` |
| `CheckForAnyScope` | `CheckTokenForAnyScope` |
| `CheckCredentials` (abstract) | `ValidateToken` |
**Projects affected**: QLS Handling.
### 29. `ClientRepository::create()` now protected
Use named factory methods instead:
| Old | New |
|-----|-----|
| `$repo->create(null, $name, '')` | `$repo->createClientCredentialsGrantClient($name)` |
| `$repo->createPersonalAccessClient(...)` | `$repo->createPersonalAccessGrantClient($name)` |
New methods return a `Client` with `$client->plainSecret` property containing the unhashed secret.
**Projects affected**: QLS Handling.
### 30. `setSecretAttribute()` removed
Passport 13 uses an Eloquent `Attribute` mutator that auto-hashes on assignment. Just set `$client->secret = $value;`.
**Projects affected**: QLS Handling.
### 31. No database migration required
Passport 13 is backward compatible with the old schema. `ClientRepository::create()` auto-detects columns via `getColumnListing()`.
However, the Passport 13 factory writes to new column names, so you may need a custom `ClientFactory` that maps to the old schema until you migrate to the new schema.
**Projects affected**: QLS Handling.
### 32. Config cleanup
Remove deprecated config keys from `config/passport.php`:
- `client_uuids` — UUIDs are now always used
- `personal_access_client` — personal access clients table removed
**Projects affected**: QLS Handling.
---
## 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.
### 33. Automated upgrade tool (`@tailwindcss/upgrade`) often fails
**Problem**: The upgrade tool fails with:
- `Cannot destructure property 'negative'` (callback-based theme extensions)
- `variants is not a function` (third-party plugins like `@formkit/themes/tailwindcss`)
- `Cannot apply unknown utility class 'pl-container'` (`@apply` referencing custom classes)
- Refuses dirty git state (run with `--force`)
- Scans backup directories (`node_modules.bak`)
**Recommended workflow**:
1. Always try the automated tool first
2. If it errors, resolve blockers and re-run (do not immediately switch to manual migration)
3. Comment out problematic custom classes temporarily if needed
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.
### 34. PostCSS plugin package split
**Problem**: Vite build fails with "trying to use `tailwindcss` directly as a PostCSS plugin".
**Fix**: Install `@tailwindcss/postcss` and update `postcss.config.js`:
```js
// Old
module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } }
// New
module.exports = { plugins: { '@tailwindcss/postcss': {} } }
```
Remove `autoprefixer` package (no longer needed).
**Projects affected**: All projects.
### 35. `@layer base` → `@utility` for custom utility classes
**Problem**: Custom classes defined with `@apply` inside `@layer base {}` fail with `Cannot apply unknown utility class`.
**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.
### 36. `@import` must precede all other statements
**Problem**: Warning about `@import` appearing after `@theme {}`.
**Fix**: Move all `@import` statements to the very top of the CSS file, right after `@import "tailwindcss"`.
**Projects affected**: Deversspecialist, Goos.
### 37. Tailwind v4 silently overrides custom `.container` class
**Problem**: Major frontend layout degradation after upgrade. Tailwind v4 no longer supports `corePlugins.container = false` from the JS config in CSS-first mode. The core `.container` utility is generated and overrides the project's custom `.container`.
**Fix**: In `resources/css/app.css`, add:
```css
@source not inline('container');
@source not inline('container!');
```
**Verification**: Built CSS should contain only the custom `.container` rule.
**Projects affected**: Contentmakers.
### 38. Remove stale `tailwind.config.js` after migration
**Problem**: After migrating to CSS-first config, the old JS config file remains, creating ambiguity.
**Fix**: After verifying no `@config` references exist in the CSS, remove `tailwind.config.js`.
**Projects affected**: Contentmakers, Deversspecialist, Goos.
### 39. Blade-injected runtime colors require `@theme inline`
**Problem**: Color utilities tied to runtime CSS variables (e.g., from `app.blade.php`) behave inconsistently.
**Fix**: Use `@theme inline` instead of `@theme` for color tokens that reference runtime CSS variables:
```css
@theme inline {
--color-primary: var(--primary-color);
--color-primary-medium: var(--primary-color);
}
```
**Rule**: After migration, grep for custom color utility names and verify each has a corresponding `--color-*` theme variable.
**Projects affected**: Contentmakers.
### 40. Removed TW v3 plugins (now built into v4)
These plugins no longer exist as separate packages in Tailwind v4:
- `@tailwindcss/forms`
- `@tailwindcss/typography`
- `@tailwindcss/aspect-ratio`
- `autoprefixer`
Remove them from `devDependencies`. Use `--force` if `npm uninstall` fails with peer dependency conflicts.
**Projects affected**: All projects.
### 41. `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`.
**Fix**: Remove `eslint-plugin-tailwindcss` from devDependencies and ESLint config. TW v4 support is still WIP upstream.
**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.
---
## PHPUnit & Pest Upgrades
### 42. PHPUnit 12 drops `/** @test */` annotation support
**Problem**: Tests using `/** @test */` doc-comment annotations are silently not discovered. Test count drops without errors.
**Fix**: Replace all `/** @test */` annotations with `#[PHPUnit\Framework\Attributes\Test]` attribute. Add `use PHPUnit\Framework\Attributes\Test;` import. Alternatively, prefix methods with `test_`.
**Rule**: After PHPUnit major upgrades, always compare test counts to the baseline.
**Projects affected**: Contentmakers, Goos.
### 43. Pest v4 requires `protected setUp()` in TestCase
**Problem**: `Access level to Pest\Concerns\Testable::setUp() must be public (as in class Tests\TestCase)` — fatal error on any test run.
**Fix**: Change `public function setUp(): void` to `protected function setUp(): void` in `tests/TestCase.php`.
**Projects affected**: Contentmakers, Goos.
### 44. Pint can break setUp() visibility
**Problem**: Running `vendor/bin/pint` can normalize `setUp()` method visibility in a way that conflicts with the TestCase chain, causing `setUp() visibility conflict (must be public)`.
**Fix**: Remove no-op `setUp()` overrides from affected tests. Always re-run tests after Pint on upgrade branches.
**Projects affected**: Contentmakers.
### 45. PHPUnit XML config deprecation warning
**Problem**: `Your XML configuration validates against a deprecated schema` — non-blocking, cosmetic warning from PHPUnit 12.
**Fix**: Run `--migrate-configuration` if desired, or ignore (non-blocking).
**Projects affected**: Deversspecialist.
### 46. Hidden regressions surfaced after restoring test discovery
**Problem**: After fixing `@test` → `#[Test]`, previously-hidden test failures appear (e.g., `Call to undefined function get_classes_in_namespace()`).
**Fix**: Treat newly exposed failures as real upgrade regressions and fix them. Example: add missing helper functions locally if dependencies no longer provide them.
**Projects affected**: Contentmakers.
---
## ESLint Migration
### 47. `eslint-plugin-vue` v10 requires flat config migration
**Problem**: Linting fails with legacy config errors (`plugin:vue/vue3-recommended` not found).
**Fix**: Create `eslint.config.cjs` (or `.mjs`) and migrate rules/plugins from `.eslintrc.json`. Keep ESLint on v9 (v10 may have additional peer compatibility issues with `@typescript-eslint` v8).
**Rule**: Treat ESLint plugin major upgrades as config-schema migrations, not package-only updates.
**Projects affected**: Contentmakers.
### 48. npm dependency graph deadlock during ESLint upgrades
**Problem**: `npm install` fails repeatedly with `ERESOLVE could not resolve` when upgrading ESLint plugins.
**Fix**: Regenerate the npm install tree cleanly — remove `node_modules` and `package-lock.json`, then reinstall.
**Projects affected**: Contentmakers.
---
## NPM / Frontend Build
### 49. Ziggy v2 requires `qs-esm` npm package
**Problem**: Vite build fails with `Rollup failed to resolve import "qs-esm"` from Ziggy v2 JS source.
**Fix**: `npm install qs-esm`
**Rule**: After Ziggy major upgrades, run a full build immediately.
**Projects affected**: Contentmakers.
### 50. `laravel-vite-plugin` v2 requires Vite 7
**Problem**: `npm install` fails — `laravel-vite-plugin ^2` has `peer vite@"^7.0.0"`.
**Fix**: Upgrade `vite` to `^7.0.0`. May need `--force` flag.
**Projects affected**: Deversspecialist, Goos.
### 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.
**Fix**: Add missing packages as explicit direct dependencies.
**Rule**: After lock regeneration, treat unresolved imports as missing direct dependency declarations.
**Projects affected**: Contentmakers.
### 52. Duplicate npm dependency entries
**Problem**: npm warns about removing packages from `dependencies` in favor of `devDependencies` (or vice versa).
**Fix**: Let npm normalize. Avoid duplicating build-only packages across both sections in `package.json`.
**Projects affected**: Contentmakers.
### 53. `@vuepic/vue-datepicker` v12 breaking changes
**Problem**: Default export removed; locale and format props changed.
**Fix**:
```js
// Old
import VueDatePicker from '@vuepic/vue-datepicker'
// New
import { VueDatePicker } from '@vuepic/vue-datepicker'
```
Additionally:
- `locale` prop now requires a date-fns `Locale` object instead of a string: `import {nl} from "date-fns/locale"`, change `:locale="'nl'"` to `:locale="nl"`
- `format` prop renamed to `formats` with sub-properties: change `format="dd-MM-yyyy"` to `:formats="{ input: 'dd-MM-yyyy' }"`
**Projects affected**: Deversspecialist.
---
## Inertia v1 → v2
### 54. SSR config change in `vite.config.js`
**Problem**: `@inertiajs/server` no longer exists in Inertia v2.
**Fix**: Change `ssr.noExternal` from `['@inertiajs/server']` to `['@inertiajs/vue3']` in `vite.config.js`.
**Projects affected**: Goos.
---
## Browser Testing
### 55. Pest browser tests need Playwright runtime
**Problem**: Browser tests fail on clean machines if Playwright browser binaries are not installed.
**Fix**: After `npm install playwright`, run `npx playwright install` (or `npx playwright install chromium`).
**Rule**: Include Playwright browser install in local + CI bootstrap.
**Projects affected**: Contentmakers, Goos.
### 56. Browser title assertions can be empty on Inertia pages
**Problem**: `<title>` can be empty at initial render timing on Inertia pages.
**Fix**: Use `assertSourceHas(...)` + smoke assertions instead of strict immediate title assertion.
**Projects affected**: Contentmakers.
### 57. `assertSee()` can fail on non-SSR Inertia pages
**Problem**: Text is present in response payload but not as immediate visible server-rendered DOM.
**Fix**: Use `assertSourceHas(...)` for payload-level assertions on client-rendered Inertia pages. Use `assertNoSmoke()` to catch JS errors and console logs.
**Projects affected**: Contentmakers, Goos.
---
## Post-Upgrade Verification Checklist
Run these checks after completing all upgrade phases:
```bash
# 1. PHP tests (compare count to baseline!)
php artisan test --compact
# 2. Frontend build
npm run build
# 3. Code style
vendor/bin/pint --dirty
# 4. Filament assets
php artisan filament:upgrade --no-interaction
# 5. Application info
php artisan about
# 6. Remaining outdated packages
composer outdated --direct --format=json
npm outdated --json
# 7. ESLint (if configured)
npx eslint resources/js/app.js resources/js/ssr.js
# 8. Browser tests (if available)
./vendor/bin/pest tests/Browser/
# 9. Filament namespace scan (check for missed rector transforms)
grep -r "use Filament\\Pages\\Actions;" app/ cms/ commerce/ modules/ support/ 2>/dev/null
grep -r "use Filament\\Forms\\Form;" app/ cms/ commerce/ modules/ support/ 2>/dev/null
grep -r "use Filament\\Forms\\Get;" app/ cms/ commerce/ modules/ support/ 2>/dev/null
grep -r "use Filament\\Forms\\Set;" app/ cms/ commerce/ modules/ support/ 2>/dev/null
```
**Note**: `php artisan route:list` may fail if any controller constructor has `abort_unless()` calls. Use `php artisan about` instead for a quick framework verification.
---
## Recommended Upgrade Order
Based on experience across all 5 projects, this order minimizes re-work:
1. **Pre-flight**: Create branch, record baseline tests + build status
2. **Composer blockers**: Replace/remove packages that block Laravel 12 (codezero, resend, laravel-lang)
3. **Laravel 12**: Update `laravel/framework ^12` + Symfony packages + debugbar + other direct deps
4. **Clear caches**: Delete `bootstrap/cache/packages.php` and `services.php`, run `composer dump-autoload`
5. **Verify**: Run tests + build
6. **Filament v3 → v4 → v5**: Run rector for each step, for each custom directory. Fix missed transforms manually.
7. **Verify**: Run tests + build
8. **Tailwind v3 → v4** (separate step, requires developer): Try automated tool first; fall back to manual. Update PostCSS config. Remove old plugins. **A developer must visually verify the frontend after this step** — open key pages in a browser and compare against the pre-upgrade state. A passing build does not guarantee correct layout.
9. **Verify**: Run tests + build + **manual visual check by developer**
10. **Pest/PHPUnit upgrade**: Update to Pest v4 / PHPUnit 12. Fix `setUp()` visibility, `@test` annotations.
11. **Verify**: Run tests (count must match baseline!)
12. **NPM major updates**: Upgrade remaining frontend packages. Fix breaking import changes.
13. **Verify**: Run build + tests
14. **ESLint**: Handle flat config migration if upgrading ESLint plugins
15. **Final verification**: Full checklist above
16. **Browser smoke tests**: Set up and run browser tests to catch runtime/rendering issues
---
## Packages That Upgraded Cleanly
These packages upgraded without issues across multiple projects. No special handling needed — just update the version constraint and run `composer update`. Listed here so the AI does not waste time over-researching them.
| Package | Typical Upgrade | Notes |
|---------|-----------------|-------|
| `darkaonline/l5-swagger` | 9 → 10 | No code changes |
| `spatie/eloquent-sortable` | 4 → 5 | No code changes |
| `spatie/laravel-data` | 4.14 → 4.19 | Minor, constraint relaxation only |
| `spatie/laravel-medialibrary` | 11.17 → 11.18 | Minor |
| `mollie/laravel-mollie` | 3 → 4 | No code changes |
| `symfony/http-client` | 7 → 8 | No code changes (PHP 8.4 already satisfied) |
| `symfony/mailgun-mailer` | 7 → 8 | No code changes |
| `barryvdh/laravel-debugbar` | 3 → 4 | Only issue is stale autoload cache (see #1) |
| `resend/resend-laravel` | 0.x → 1.x | No API changes |
| `jeffgreco13/filament-breezy` | 2 → 3 | Works with Filament v5 |
| `ariaieboy/filament-currency` | 1 → 3 | Works with Filament v5 + Laravel 12 |
| `amidesfahani/filament-tinyeditor` | 3 → 4 | No code changes |
| `ralphjsmit/laravel-filament-components` | 2 → 3 | No code changes |
| `filament/spatie-laravel-media-library-plugin` | 3 → 5 | No code changes |
| `filament/spatie-laravel-settings-plugin` | 3 → 5 | No code changes |
| `filament/spatie-laravel-tags-plugin` | 3 → 5 | No code changes |
| `nunomaduro/collision` | 7 → 8 | No code changes |
| `laravel/sanctum` | 3 → 4 | No code changes |
---
## Projects Covered
| Project | Log File |
|---------|----------|
| Contentmakers | `Logs/upgrade-log-contentmakers.md` |
| QLS Handling | `Logs/upgrade-log-qlshandling.md` |
| Deversspecialist | `Logs/upgrade-log-deversspecialist.md`, `Logs/upgrade-log-deversspecialist-composer.md` |
| Cleanshopping | `Logs/upgrade-log-cleanshopping.md` |
| Goos | `Logs/upgrade-log-goos.md` |
---
*Last updated: 2026-02-20*

43
Work/Projects/Laravel-v12-Migration/Logs/TEMPLATE.md
View File

@@ -1,43 +0,0 @@
# 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
-

0
Work/Projects/Laravel-v12-Migration/UPGRADE-LOG-CLEANSHOPPING.md → Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-cleanshopping.md
View File

0
Work/Projects/Laravel-v12-Migration/UPDATE_LOG-contentmakers.md → Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-contentmakers.md
View File

0
Work/Projects/Laravel-v12-Migration/update-deversspecialist.md → Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-deversspecialist-composer.md
View File

0
Work/Projects/Laravel-v12-Migration/UPGRADE-LOG-deversspecialist.md → Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-deversspecialist.md
View File

0
Work/Projects/Laravel-v12-Migration/UPGRADE-LOG-GOOS.md → Work/Projects/Laravel-v12-Migration/Logs/upgrade-log-goos.md
View File

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

@@ -0,0 +1,138 @@
# Composer Dependency Upgrades - Feb 2026
## Summary of Upgrades
| Package | From | To | Code Changes |
| ------------------------ | ------ | ------ | ------------------------------------------------------------ |
| spatie/laravel-data | 4.14.0 | 4.19.1 | Constraint only (`"4.14"` -> `"^4.14"`) |
| spatie/eloquent-sortable | 4.5.2 | 5.0.0 | None |
| resend/resend-laravel | 0.17.0 | 1.2.0 | None |
| symfony/http-client | 7.4.5 | 8.x | None |
| symfony/mailgun-mailer | 7.4.0 | 8.x | None |
| darkaonline/l5-swagger | 9.0.1 | 10.x | None |
| livewire/livewire | 3.7.10 | 4.x | Config key renames |
| laravel/passport | 12.4.2 | 13.x | Middleware, service provider, factory override, test updates |
---
## Livewire 3 -> 4
### Config Changes (`config/livewire.php`)
| Old Key | New Key |
| ------------------ | ----------------------- |
| `layout` | `component_layout` |
| `lazy_placeholder` | `component_placeholder` |
### What We Didn't Need to Change
- `wire:model` behavior: Our usage (`wire:model="barcode"` without `.live`) works the same in v4 (deferred by default in both v3 and v4).
- `wire-elements/modal` v3.0.4: Already compatible with Livewire 4 (requires `^3.2.3|^4.0`).
- `Route::get()` with Livewire component: Still works in v4. `Route::livewire()` is recommended but not required.
- Component tag closing: All our `<livewire:>` tags were already properly self-closed.
- `wire:transition` / `wire:scroll`: Not used in this app.
### Potential Gotchas for Next Time
- **`wire:model.blur` / `.change` behavior changed**: In v4, these modifiers now control client-side state sync timing too. Add `.live` before them if you want old behavior: `wire:model.live.blur`.
- **Component tags must be closed**: Unclosed `<livewire:component>` tags are interpreted as slot content in v4.
- **`@livewireStyles`/`@livewireScripts`**: Still work with `inject_assets => true`, but you can use `@livewireScriptConfig` if bundling Livewire into your JS build.
---
## Laravel Passport 12 -> 13
### Breaking Changes Encountered
#### 1. `Passport::hashClientSecrets()` Removed
Secrets are now ALWAYS hashed in v13. Remove all calls to `Passport::hashClientSecrets()`.
**Files fixed:**
- `modules/Auth/AuthServiceProvider.php` - Removed the call
- `tests/Feature/Scopes/Api/Http/Middleware/CheckDecoCredentialsTest.php` - Removed from tests
#### 2. `CheckClientCredentials` Middleware Renamed to `CheckToken`
All credential-checking middleware were renamed:
| Old Name | New Name |
| ----------------------------------- | ----------------------- |
| `CheckClientCredentials` | `CheckToken` |
| `CheckClientCredentialsForAnyScope` | `CheckTokenForAnyScope` |
| `CheckScopes` | `CheckToken` |
| `CheckForAnyScope` | `CheckTokenForAnyScope` |
| `CheckCredentials` (abstract) | `ValidateToken` |
**Files fixed:**
- `app/Http/Kernel.php` - Updated import and all 3 middleware group references
#### 3. `ClientRepository::create()` Now Protected
The `create()` method on `ClientRepository` is now `protected`. Use the named factory methods instead:
| Old | New |
| ---------------------------------------- | -------------------------------------------------- |
| `$repo->create(null, $name, '')` | `$repo->createClientCredentialsGrantClient($name)` |
| `$repo->createPersonalAccessClient(...)` | `$repo->createPersonalAccessGrantClient($name)` |
The new methods return a `Client` with `$client->plainSecret` property containing the unhashed secret.
**Files fixed:**
- `tests/Feature/Http/Controllers/Api/V1/AirWaybillMilestone/AirWaybillMilestoneControllerTest.php`
- `tests/Feature/Scopes/Api/Http/Middleware/CheckDecoCredentialsTest.php`
- `scopes/Api/Tests/Http/Controllers/V1/Outbound/PickupControllerTest.php`
- `scopes/Api/Tests/Pest.php`
#### 4. `setSecretAttribute()` No Longer Exists
Passport 13 uses an Eloquent `Attribute` mutator for `secret` that auto-hashes on assignment. Instead of manually setting secrets:
```php
// Old (v12)
$client->setSecretAttribute($secret);
$client->save();
// New (v13) - just set the attribute, it auto-hashes
$client->secret = $secret;
$client->save();
// Or better - use the factory/repository which exposes plainSecret
$client = $repo->createClientCredentialsGrantClient($name);
$plainSecret = $client->plainSecret; // Available immediately after creation
```
#### 5. No Database Migration Needed (Backward Compatible)
Passport 13 introduces new column names (`owner_type`/`owner_id`, `redirect_uris`, `grant_types`, `scopes`) but is **fully backward compatible** with the old schema:
- `ClientRepository::create()` auto-detects columns via `getColumnListing()` and writes to whichever exist
- `Client::redirectUris()` accessor falls back to reading `redirect` column
- `Client::grantTypes()` accessor infers from `personal_access_client`/`password_client` columns
- `Client::firstParty()` checks for `user_id` first, falls back to `owner_id`
The Passport 13 **factory** writes to new columns, so we override it with `modules/Auth/Database/Factories/ClientFactory.php` that maps to the old schema. The `Client` model's `newFactory()` method returns our custom factory.
#### 6. `config/passport.php` Cleanup
Removed deprecated config keys:
- `client_uuids` - UUIDs are now always used (default in v13)
- `personal_access_client` - Personal access clients table removed
### What We Didn't Need to Change
- `Passport::useTokenModel()` - Still works the same
- `Passport::useClientModel()` - Still works the same
- `Passport::ignoreRoutes()` - Still works
- `Token` model (custom) extending `Laravel\Passport\Token` - Still compatible
- `AccessTokenController` - Still exists, `TokenController` still extends it
- `auth('passport')->client()` - Still works in middleware
- `Token::findFromRequest()` - Still works (JWT parsing unchanged)
### Production Deployment Notes
- No database migration required - Passport 13 is backward compatible with the old schema
- Existing hashed secrets remain valid since v12 was already hashing them
- If you want to migrate to the new schema in the future, see https://github.com/laravel/passport/blob/13.x/UPGRADE.md for the official migration
- The `oauth_personal_access_clients` table is redundant in v13 and can be dropped
- When migrating to new schema: remove the custom `ClientFactory` override and `newFactory()` from the Client model

132
Work/Projects/Laravel-v12-Migration/TEMPLATE.md Normal file
View File

@@ -0,0 +1,132 @@
# Update Log: [Project Name] — Laravel 11 → 12 + Ecosystem
> **Date:** YYYY-MM-DD
> **Branch:** `upgrade/laravel-12-full`
> **AI Tool:** (e.g., Claude Code, Cursor)
---
## Starting State
| Package | Before | Target |
|---------|--------|--------|
| PHP | | (no change expected) |
| laravel/framework | | ^12.0 |
| filament/filament | | ^5.0 |
| livewire/livewire | | ^4.0 |
| tailwindcss | | ^4.0 |
| pestphp/pest | | ^4.0 |
| | | |
**Baseline tests:** _X passed (Y assertions)_
**Baseline build:** _Success / Fail_
---
## Upgrade Phases
### Phase 1: Pre-Flight
- [ ] Branch created
- [ ] Baseline tests recorded
- [ ] Baseline build verified
- [ ] Reference document consulted (`Laravel-12-Migration-Problems-and-Solutions.md`)
### Phase 2: Composer — Laravel 12
- [ ] Blockers resolved (codezero, resend, laravel-lang, etc.)
- [ ] Laravel framework ^12 installed
- [ ] Bootstrap cache cleared
- [ ] Tests pass, build succeeds
### Phase 3: Filament v3 → v4 → v5
- [ ] Rector v4 run for each directory: `app/`, `modules/`, `cms/`, etc.
- [ ] Rector v5 run for each directory
- [ ] Manual namespace fixes applied (grep scan)
- [ ] Incompatible plugins replaced
- [ ] Tests pass, build succeeds
### Phase 4: Tailwind v3 → v4
- [ ] Automated upgrade tool attempted
- [ ] PostCSS config updated
- [ ] CSS directives migrated (@theme, @utility, @import order)
- [ ] Old TW plugins removed
- [ ] Build succeeds
- [ ] **Developer visual check completed** (pages inspected in browser)
### Phase 5: Pest / PHPUnit Upgrade
- [ ] Pest v4 / PHPUnit 12 installed
- [ ] `setUp()` visibility fixed
- [ ] `@test` annotations migrated to `#[Test]`
- [ ] Test count matches baseline
### Phase 6: NPM Updates
- [ ] Major frontend packages upgraded
- [ ] Breaking import changes fixed
- [ ] Build succeeds
### Phase 7: Final Verification
- [ ] Tests pass (count matches baseline)
- [ ] Build succeeds (client + SSR)
- [ ] Pint passes
- [ ] `composer outdated --direct` reviewed
- [ ] `npm outdated` reviewed
- [ ] `php artisan about` confirms Laravel 12
---
## Exceptions & Issues
Record every error, warning, or unexpected behavior here. Use this format:
### 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:** What resolved it.
**Files affected:** List of files changed.
<!-- Repeat for each issue -->
---
## Packages Changed
| Package | From | To | Notes |
|---------|------|----|-------|
| | | | |
---
## What Worked Without Issues
List packages and steps that completed cleanly with no problems. This is useful for future reference so the AI does not over-research these.
-
---
## Remaining / Unresolved
Items that were not fixed, intentionally skipped, or need follow-up.
-
---
## Miscellaneous
Anything that does not fit the sections above. Observations, decisions, context, or notes for the next person.
-
---
## Recommendations for Next Session
-