# 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