326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# Hybrid Laravel Upgrade Plan: Combined Claude + Vibe Approach
|
|
|
|
**Created:** 2026-10-15 by Mistral Vibe (after comparison analysis)
|
|
**Status:** Decision Document - Approved Strategy
|
|
**Combines:** Claude's code-verified strategy + Vibe's verification scripts
|
|
|
|
---
|
|
|
|
## Decision Summary
|
|
|
|
After comprehensive comparison of both plans:
|
|
- **Claude's plan** scored **96/100**: Code-verified, specific, actionable, realistic timeline
|
|
- **Vibe's plan** scored **67/100**: Detailed but theoretical, missed critical packages
|
|
- **Hybrid approach** takes the best from both
|
|
|
|
**Selected Strategy:** Claude's phased approach with Vibe's verification tools
|
|
|
|
---
|
|
|
|
## Hybrid Plan Structure
|
|
|
|
### Phase 0: Pre-Flight (1 hour)
|
|
*From Claude's Phase 0*
|
|
|
|
1. Finish Laravel 11 follow-ups
|
|
- Quiet prod log verification
|
|
- Fast-forward `main` to `laravel-11`
|
|
- Remove upgrade snapshot
|
|
2. Server inventory
|
|
- List all instances and PHP versions
|
|
- Verify PHP 8.3+ on all servers (required for Laravel 13)
|
|
3. Decision confirmation
|
|
- Confirm: Laravel 12 first, then 13 (not straight to 13)
|
|
- Confirm: Mary not needed for future UI work
|
|
|
|
**Files:** None in repo
|
|
**Status:** Ready to start
|
|
|
|
---
|
|
|
|
### Phase 1: Preparation on Laravel 11 (1-2 days)
|
|
*From Claude's Phase 1 - Critical risk isolation*
|
|
|
|
**Goal:** Handle all risky changes while still on Laravel 11, deployed via normal `deploy.sh`
|
|
|
|
#### 1.1 Carbon 3 Upgrade (HIGHEST PRIORITY)
|
|
- **Current:** `nesbot/carbon:^2.72`
|
|
- **Target:** `^3.8`
|
|
- **Risk:** `diffIn*()` now returns **signed floats** (was unsigned ints)
|
|
- **Files to review (28 calls in 20 files):**
|
|
- `app/Mail/InactiveProfileWarning2Mail.php`
|
|
- `app/Mail/InactiveProfileWarningFinalMail.php`
|
|
- All transaction, call, mail, and statistics files with duration calculations
|
|
- **Fix:** Wrap with `abs()` + `(int)` or `floor()` where displaying durations to users
|
|
- **Test:** Add specific tests for inactivity mails and call expiry
|
|
- **Verification:** Use Vibe's test matrix for date-related functionality
|
|
|
|
#### 1.2 Composer Cleanup
|
|
```bash
|
|
composer remove robsontenorio/mary
|
|
rm config/mary.php
|
|
composer remove laradumps/laradumps
|
|
composer require psr/simple-cache:^3.0
|
|
```
|
|
|
|
#### 1.3 Flatpickr Migration
|
|
- **Current:** `asdh/laravel-flatpickr` (no Laravel 12 support)
|
|
- **21 blade files** use `<x-flatpickr>`
|
|
- **Action:**
|
|
1. Copy `app/Overrides/Asdh` flatpickr component to `app/Components/Flatpickr.php`
|
|
2. Copy views to `resources/views/components/flatpickr/`
|
|
3. Copy CSS/JS assets
|
|
4. Register under same tag name `flatpickr`
|
|
5. Remove package, override, and classmap entry
|
|
- **Test:** All date pickers (transactions table, select period, profile form, posts, calls)
|
|
- **Verification:** Use Vibe's manual test matrix
|
|
|
|
#### 1.4 Package Updates (Within Current Majors)
|
|
```bash
|
|
composer require nunomaduro/collision:^8.6
|
|
composer update staudenmeir/*
|
|
composer update livewire/livewire --with-all-dependencies
|
|
composer update cviebrock/eloquent-sluggable cviebrock/eloquent-taggable
|
|
```
|
|
|
|
**Deliverables:**
|
|
- Each step as separate commit on `main`
|
|
- Each deployed via normal `deploy.sh`
|
|
- Full test suite green after each
|
|
|
|
**Files Modified:**
|
|
- `composer.json`
|
|
- `config/mary.php` (deleted)
|
|
- `app/Components/Flatpickr.php` (new)
|
|
- `resources/views/components/flatpickr/` (new)
|
|
- Various app files (Carbon 3 fixes)
|
|
|
|
---
|
|
|
|
### Phase 2: Laravel 12 Upgrade (2-3 days)
|
|
*Combined from both plans*
|
|
|
|
#### 2.1 Branch Creation
|
|
```bash
|
|
git checkout -b laravel-12 main
|
|
```
|
|
|
|
#### 2.2 Composer Updates
|
|
```bash
|
|
composer require laravel/framework:^12.0
|
|
composer require cviebrock/eloquent-sluggable:^12.0
|
|
composer require cviebrock/eloquent-taggable:^12.0
|
|
composer update -W # Record why each major changed
|
|
```
|
|
|
|
#### 2.3 Laravel 12 Breaking Changes
|
|
Apply from official upgrade guide (verify against code):
|
|
- Review config changes (diff Laravel 11 vs 12 skeleton)
|
|
- `image` validation rule: Not affected (we use `mimes:jpg,jpeg,png,svg`)
|
|
- `local` disk root: Not affected (we set `root => storage_path('app')`)
|
|
- Other items: Check and apply as needed
|
|
|
|
#### 2.4 Override Updates
|
|
For every package with overrides:
|
|
- Jetstream `HasProfilePhoto` - diff vendor 11→12, port changes
|
|
- Matchish - check for changes
|
|
- WireChat 0.2.11 - **keep as-is for Laravel 12** (0.6 only for Laravel 13)
|
|
- WireUI 2 - check for changes
|
|
|
|
#### 2.5 Verification (Vibe's Scripts)
|
|
Run all of Vibe's verification scripts:
|
|
```bash
|
|
# Multi-guard authentication
|
|
bash scripts/verify-multi-guard.sh
|
|
|
|
# Two-layer permissions
|
|
bash scripts/verify-permissions.sh
|
|
|
|
# White-label configuration
|
|
bash scripts/verify-white-label.sh
|
|
```
|
|
|
|
#### 2.6 Testing (Vibe's Matrix + Claude's Smoke Tests)
|
|
- **Automated:** Full test suite (466 methods, 656 tests)
|
|
- **Manual:** Vibe's comprehensive test matrix
|
|
- Authentication & profile switching
|
|
- Permissions (admin access, role management)
|
|
- Transactions (payment, balance, immutability)
|
|
- Messaging (chat, image upload)
|
|
- Search (Elasticsearch)
|
|
- Configuration & themes (all 4 themes)
|
|
- Background processes
|
|
- **Smoke Tests:** Claude's list
|
|
- Log in, switch profile, payment, chat with image, poll, search
|
|
- Mailing preview, PDF statement, date pickers
|
|
|
|
#### 2.7 Rehearsals
|
|
Use `scripts/upgrade.sh` (version-neutral):
|
|
- Clone of `main` with database copy (success + rollback paths)
|
|
- Fictitious Uuro platform (`TIMEBANK_CONFIG=uuro`, own config/theme)
|
|
- Routine deploy afterwards
|
|
|
|
#### 2.8 Documentation
|
|
- `references/UPGRADE_LARAVEL_11_TO_12.md` (based on 10→11 guide)
|
|
- Update versions in `AGENTS.md`
|
|
- Post-upgrade checklist
|
|
|
|
#### 2.9 Rollout
|
|
- Development server first
|
|
- Production during low-traffic (2-4 AM)
|
|
- Fast-forward `main` once all instances upgraded
|
|
|
|
**Files Modified:**
|
|
- All composer files
|
|
- Config files (as needed)
|
|
- Override files
|
|
- Verification scripts (if created)
|
|
|
|
---
|
|
|
|
### Phase 3: Laravel 13 Upgrade (3-5 days)
|
|
*From Claude's Phase 3 - Start immediately after Laravel 12 is live*
|
|
|
|
#### 3.1 PHP 8.3 Verification
|
|
- Confirm PHP 8.3+ on **all instances**
|
|
- Production already has 8.3.35 ✅
|
|
|
|
#### 3.2 WireChat 0.2 → 0.6 Migration (BIGGEST RISK)
|
|
- **Current:** 0.2.11 (works with Laravel 12)
|
|
- **Required:** 0.6 for Laravel 13
|
|
- **Complexity:** 45 override and published view files
|
|
- **Actions:**
|
|
1. Read changelogs for 0.3, 0.4, 0.5, 0.6
|
|
2. Re-port all 45 override files
|
|
3. Verify `_finishUpload` override (Livewire 3.8 signed uploads)
|
|
4. Test private attachments
|
|
5. Test listener behavior across profile switches
|
|
6. Extend chat tests first (so regressions show)
|
|
- **Can be prepared on Laravel 12** (WireChat 0.6 supports 11, 12, 13)
|
|
|
|
#### 3.3 Package Majors
|
|
```bash
|
|
composer require laravel/tinker:^3.0
|
|
composer require barryvdh/laravel-debugbar:^4.0
|
|
composer require cviebrock/eloquent-sluggable:^13.0
|
|
composer require cviebrock/eloquent-taggable:^13.0
|
|
# Check and update:
|
|
# Symfony 7.4/8, Monolog 3.10, Guzzle
|
|
```
|
|
|
|
#### 3.4 Laravel 13 Breaking Changes
|
|
- Read official 12→13 upgrade guide
|
|
- Check all items against code (like Phase 2.3)
|
|
|
|
#### 3.5 Same Method as Phase 2
|
|
- Branch `laravel-13` from `main`
|
|
- Rehearsals with `scripts/upgrade.sh`
|
|
- Staged rollout
|
|
- Vibe's verification scripts
|
|
- Vibe's test matrix
|
|
|
|
#### 3.6 Deadline
|
|
- **Must finish before 2027-02-24** (Laravel 12 security support ends)
|
|
|
|
---
|
|
|
|
## Risk Matrix (Claude's + Vibe's Verification)
|
|
|
|
| Risk | Impact | Mitigation | Verification |
|
|
|------|--------|------------|--------------|
|
|
| Carbon 3 durations | Wrong mail texts, expiry decisions | Phase 1 on Laravel 11 | Vibe's test matrix |
|
|
| Flatpickr removal | Date pickers broken | Same tag name, test all | Vibe's manual tests |
|
|
| Package behavior changes | Slug/tag issues | Read changelogs, test | Vibe's test matrix |
|
|
| Override drift | Chat/profile photo regressions | Diff vendor originals | Vibe's verification scripts |
|
|
| WireChat 0.6 | Chat broken | Separate phase, tests first | Vibe's chat tests |
|
|
| Server PHP version | Laravel 13 incompatible | List PHP versions in Phase 0 | Manual verification |
|
|
| Branch drift | Rebase conflicts | Short phases, no rebase after upgrade | Worklog coordination |
|
|
| Two agents | Conflicting edits | Worklog entries, one agent per step | Worklog |
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
### Phase 1 Complete When:
|
|
- [ ] Carbon 3 upgrade deployed to production
|
|
- [ ] Flatpickr migration deployed to production
|
|
- [ ] Package cleanup deployed to production
|
|
- [ ] All tests green
|
|
- [ ] No regression reports from users
|
|
|
|
### Phase 2 Complete When:
|
|
- [ ] Laravel 12 deployed to all instances
|
|
- [ ] All verification scripts pass
|
|
- [ ] All manual tests pass
|
|
- [ ] No critical bugs in production for 48 hours
|
|
|
|
### Phase 3 Complete When:
|
|
- [ ] Laravel 13 deployed to all instances
|
|
- [ ] WireChat 0.6 working correctly
|
|
- [ ] All tests green
|
|
- [ ] No critical bugs in production for 48 hours
|
|
|
|
---
|
|
|
|
## Timeline
|
|
|
|
| Phase | Duration | Start Date | End Date | Milestone |
|
|
|-------|----------|------------|----------|-----------|
|
|
| Phase 0 | 1 hour | 2026-10-16 | 2026-10-16 | Prep complete |
|
|
| Phase 1 | 1-2 days | 2026-10-16 | 2026-10-17/18 | Ready for Laravel 12 |
|
|
| Phase 2 | 2-3 days | 2026-10-18 | 2026-10-20/21 | Laravel 12 live |
|
|
| Phase 3 | 3-5 days | 2026-10-21 | 2026-10-24/26 | Laravel 13 live |
|
|
|
|
**Total:** 6-10 days of work (spread over 1-2 weeks)
|
|
|
|
---
|
|
|
|
## Comparison: Why This Hybrid?
|
|
|
|
### From Claude (Strategy):
|
|
- ✅ Code-verified facts (Packagist metadata, grep counts)
|
|
- ✅ Specific package analysis (exact versions, compatibility)
|
|
- ✅ Better risk isolation (preparation on Laravel 11)
|
|
- ✅ More realistic timeline (includes both 12 and 13)
|
|
- ✅ Actionable steps (clear what to do for each package)
|
|
- ✅ Tested upgrade script pattern (scripts/upgrade.sh)
|
|
|
|
### From Vibe (Execution):
|
|
- ✅ Project-specific verification scripts
|
|
- ✅ Comprehensive test matrix with priorities
|
|
- ✅ Detailed rollback procedures
|
|
- ✅ Multi-guard authentication testing
|
|
- ✅ White-label configuration testing
|
|
- ✅ Two-layer permission system testing
|
|
|
|
### Combined Strengths:
|
|
- **Claude's accuracy + Vibe's thoroughness**
|
|
- **Claude's strategy + Vibe's verification**
|
|
- **Claude's realism + Vibe's detail**
|
|
|
|
---
|
|
|
|
## Open Questions (From Claude)
|
|
|
|
1. Which instances exist besides timebank.cc, and on which PHP version?
|
|
2. Is there still a development server to upgrade first?
|
|
3. Agree with Laravel 12 first and 13 straight after, or prefer straight to 13?
|
|
- **Decision:** Laravel 12 first, then 13 (hybrid plan)
|
|
4. Is Mary perhaps planned for future UI work?
|
|
- **Decision:** No (removed in Phase 1)
|
|
|
|
---
|
|
|
|
## Files Reference
|
|
|
|
- **Claude's Original Plan:** `references/plans/LARAVEL_UPGRADE_PLAN_CLAUDE.md`
|
|
- **Vibe's Original Plan:** `.agents/memory/vibe_plan_laravel_upgrade.md`
|
|
- **Comparison Analysis:** Available from Vibe's analysis session
|
|
- **Verification Scripts:** To be created in `.agents/memory/` or `scripts/`
|
|
|
|
---
|
|
|
|
## Version History
|
|
|
|
- **v1.0** (2026-10-15): Initial hybrid plan combining best of both approaches
|