ronald/timebank-cc-public
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
timebank-cc-public/references/plans/LARAVEL_UPGRADE_PLAN_HYBRID.md
T

11 KiB
Raw Permalink Blame History

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

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)

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

git checkout -b laravel-12 main

2.2 Composer Updates

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:

# 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

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
Reference in new issue View Git Blame Copy Permalink