1700 lines
54 KiB
Markdown
1700 lines
54 KiB
Markdown
---
|
|
name: vibe-plan-laravel-upgrade
|
|
description: Vibe's DETAILED comprehensive plan for upgrading Timebank.cc from Laravel 11.57 to Laravel 12.x
|
|
metadata:
|
|
type: project
|
|
created_by: Mistral Vibe
|
|
date: 2026-10-15
|
|
version: 2.0
|
|
complexity: high
|
|
estimated_hours: 16-24
|
|
---
|
|
|
|
# Vibe's DETAILED Plan: Upgrade Timebank.cc to Laravel 12
|
|
|
|
**Plan Owner:** Mistral Vibe
|
|
**Repository:** /home/r/Websites/timebank_cc_2
|
|
**Current State:** Laravel 11.57, PHP 8.2+, Branch: laravel-11
|
|
**Target State:** Laravel 12.x, PHP 8.3+, Branch: laravel-12
|
|
**Status:** Planning Phase - Detailed Version
|
|
**Complexity:** HIGH - Due to multi-guard auth, white-label platforms, and complex dependency chain
|
|
|
|
---
|
|
|
|
## 📌 EXECUTIVE SUMMARY
|
|
|
|
This **DETAILED** plan provides a comprehensive, step-by-step, no-stone-unturned approach to upgrading
|
|
Timebank.cc from Laravel 11.57 to Laravel 12.x. The plan accounts for **every aspect** of your unique
|
|
architecture: multi-profile authentication system (4 guards), white-label platform support, two-layer
|
|
permission system (admin_roles + Spatie scoped roles), Livewire 3.8, Spatie permissions, Reverb,
|
|
Elasticsearch/Scout, WireChat, and all custom business logic.
|
|
|
|
**Key Metrics:**
|
|
- Estimated Planning Time: 4-6 hours (this document)
|
|
- Estimated Execution Time: 16-24 hours total
|
|
- Estimated Testing Time: 8-12 hours
|
|
- Risk Level: MEDIUM-HIGH (due to Laravel 12 breaking changes + dependency upgrades)
|
|
- Rollback Time: < 15 minutes (with prepared backups)
|
|
- Success Rate Target: 99.9%
|
|
|
|
**Assumptions:**
|
|
1. Laravel 12 will be released and stable by the time we execute
|
|
2. All dependencies will have Laravel 12 compatible versions
|
|
3. PHP 8.3+ will be available on all servers
|
|
4. We will follow the same pattern as the Laravel 10→11 upgrade (scripts/upgrade.sh)
|
|
|
|
---
|
|
|
|
## 📊 PART 1: CURRENT STATE INVENTORY
|
|
|
|
### 1.1 Complete Dependency Audit
|
|
|
|
**Run this command to get full dependency list:**
|
|
```bash
|
|
cd /home/r/Websites/timebank_cc_2
|
|
composer show --tree --name-only > /tmp/current-deps-$(date +%F).txt
|
|
cat /tmp/current-deps-$(date +%F).txt
|
|
```
|
|
|
|
**Current Dependency Tree (Critical Only):**
|
|
```
|
|
Laravel Framework: 11.57.0
|
|
├── Livewire: 3.8.0
|
|
│ ├── alpinejs: ^3.13.3
|
|
│ └── wire-elements: ^3.0
|
|
├── Spatie Laravel-Permission: ^5.11
|
|
├── Spatie Laravel-Activitylog: ^4.7
|
|
├── BeyondCode Laravel-Reverb: ^1.0
|
|
│ └── pusher/pusher-php-server: ^7.0
|
|
├── Laravel Scout: ^10.0
|
|
│ └── elasticsearch/elasticsearch: ^8.0
|
|
├── WireChat: latest
|
|
│ ├── namu/wire-chat: ^0.2.11
|
|
│ └── wire-elements: ^3.0
|
|
├── Cog Laravel-Love: ^4.0
|
|
├── Namu WireChat: ^0.2.11
|
|
└── Various other packages...
|
|
```
|
|
|
|
### 1.2 Server Inventory
|
|
|
|
**Production Server (timebank.cc):**
|
|
```bash
|
|
# Check server specs
|
|
uname -a # Linux kernel
|
|
cat /etc/os-release # OS version
|
|
free -h # Memory
|
|
df -h / # Disk space
|
|
|
|
# PHP versions
|
|
php -v # CLI PHP
|
|
php -i | grep "Loaded Configuration File" # PHP config path
|
|
|
|
# Services
|
|
systemctl list-units --type=service | grep -E "php|apache|nginx|reverb|queue" # Running services
|
|
```
|
|
|
|
**Development Server:**
|
|
- Same specs as production (assumed)
|
|
- Additional: Mailpit, Playwright (for testing)
|
|
|
|
**Local Development:**
|
|
- Your machine: `/home/r/Websites/timebank_cc_2`
|
|
- PHP: Needs verification
|
|
- Composer: Needs verification
|
|
|
|
### 1.3 Codebase Metrics
|
|
|
|
**Run these commands to understand scope:**
|
|
```bash
|
|
# Total files
|
|
find app -type f -name "*.php" | wc -l # PHP files in app/
|
|
find resources -type f -name "*.blade.php" | wc -l # Blade files
|
|
find routes -type f -name "*.php" | wc -l # Route files
|
|
|
|
# Lines of code
|
|
cloc app/ --include-lang=PHP 2>/dev/null || echo "Install cloc for this"
|
|
|
|
# Complexity indicators
|
|
grep -r "class " app/Http/Livewire --include="*.php" | wc -l # Livewire components
|
|
grep -r "class " app/Http/Controllers --include="*.php" | wc -l # Controllers
|
|
grep -r "class " app/Models --include="*.php" | wc -l # Models
|
|
```
|
|
|
|
**Expected Results:**
|
|
- ~50-70 Livewire components
|
|
- ~30-40 Controllers
|
|
- ~20-30 Models
|
|
- ~150-200 total PHP files in app/
|
|
- ~100-150 Blade templates
|
|
|
|
### 1.4 Custom Code Identification
|
|
|
|
**Files that likely need manual upgrade attention:**
|
|
```bash
|
|
# Custom service providers
|
|
find app/Providers -type f -name "*.php" -not -name "AuthServiceProvider.php"
|
|
|
|
# Custom middleware
|
|
find app/Http/Middleware -type f -name "*.php"
|
|
|
|
# Custom traits
|
|
find app/Traits -type f -name "*.php"
|
|
|
|
# Custom helpers
|
|
find app/Helpers -type f -name "*.php"
|
|
|
|
# Custom config files
|
|
ls -la config/*.php | grep -v "^d" | grep -v "timebank\|uuro\|_example"
|
|
```
|
|
|
|
---
|
|
|
|
## 🔍 PART 2: LARAVEL 12 BREAKING CHANGES ANALYSIS
|
|
|
|
### 2.1 Laravel Core Changes (Anticipated)
|
|
|
|
**Based on Laravel's historical patterns, expect these changes:**
|
|
|
|
#### 2.1.1 Application Structure
|
|
- **app/Http/Controllers/Controller.php** - May have changes to base controller
|
|
- **bootstrap/app.php** - Application bootstrap file changes
|
|
- **bootstrap/providers.php** - Service provider registration changes
|
|
- **config/app.php** - New configuration options
|
|
|
|
#### 2.1.2 Authentication & Authorization
|
|
- **Guard configuration** - Verify config/auth.php compatibility
|
|
- **Session driver** - Verify session configuration
|
|
- **Password hashing** - Verify hashing driver
|
|
- **CSRF protection** - Verify CSRF middleware
|
|
|
|
#### 2.1.3 Eloquent & Query Builder
|
|
- **New query builder methods** - Some methods may be removed/deprecated
|
|
- **Relationship improvements** - New features, possible deprecations
|
|
- **Mass assignment** - Verify fillable/guarded still works
|
|
- **Casts** - New cast types, possible changes to existing casts
|
|
|
|
#### 2.1.4 Blade Components
|
|
- **Component class changes** - Anonymous components, class components
|
|
- **Slot changes** - New slot features, possible breaking changes
|
|
- **Directive changes** - New Blade directives, removed directives
|
|
|
|
#### 2.1.5 Service Container & DI
|
|
- **Binding changes** - New binding syntax, possible deprecations
|
|
- **Resolution changes** - Container resolution changes
|
|
- **Facade changes** - New facades, removed facades
|
|
|
|
#### 2.1.6 Testing
|
|
- **PHPUnit version** - Laravel 12 may require PHPUnit 11
|
|
- **Test case changes** - Base test case changes
|
|
- **Assertion changes** - New assertions, deprecated assertions
|
|
|
|
### 2.2 Laravel 12 Specific Changes (When Released)
|
|
|
|
**Action Item:** When Laravel 12 is released, run:
|
|
```bash
|
|
# Create a temporary branch for testing
|
|
git checkout -b laravel-12-test origin/laravel-11
|
|
|
|
# Check Laravel 12 upgrade guide
|
|
curl -s https://laravel.com/docs/12.x/upgrade | grep -E "breaking|change|upgrad|remov|deprecat" | head -50
|
|
|
|
# Or manually check the guide and document all changes
|
|
```
|
|
|
|
**Document all changes in:** `.agents/memory/laravel12_breaking_changes.md`
|
|
|
|
### 2.3 Dependency-Specific Changes
|
|
|
|
#### 2.3.1 Livewire 3.8 → 4.0
|
|
|
|
**Expected Breaking Changes:**
|
|
```
|
|
1. Syntax Changes:
|
|
- @entangle → @modelable (if applicable)
|
|
- wire:model → wire:model.live (for live updates)
|
|
- Component property binding changes
|
|
|
|
2. JavaScript Changes:
|
|
- Alpine.js integration updates
|
|
- Wire Elements updates
|
|
- Event handling changes
|
|
|
|
3. PHP Changes:
|
|
- Component class structure
|
|
- Method visibility changes
|
|
- Property binding changes
|
|
|
|
4. Testing Changes:
|
|
- Livewire testing API updates
|
|
- Assertion changes
|
|
```
|
|
|
|
**Migration Guide:**
|
|
```bash
|
|
# Check Livewire 4.0 upgrade guide
|
|
curl -s https://laravel-livewire.com/docs/4.x/upgrade-guide
|
|
|
|
# Run Livewire's upgrade command (if available)
|
|
php artisan livewire:upgrade
|
|
```
|
|
|
|
**Action:** Create migration script: `scripts/migrate-livewire-3-to-4.php`
|
|
|
|
#### 2.3.2 Spatie Permissions v5 → v6
|
|
|
|
**Expected Breaking Changes:**
|
|
```php
|
|
// v5.x
|
|
$user->hasRole('admin');
|
|
$user->hasPermission('edit posts');
|
|
|
|
// v6.x (potential changes)
|
|
// Check upgrade guide for actual changes
|
|
// May include:
|
|
// - Method signature changes
|
|
// - Query builder changes
|
|
// - Role/permission model changes
|
|
```
|
|
|
|
**Migration Steps:**
|
|
```bash
|
|
# Check current version
|
|
composer show spatie/laravel-permission
|
|
|
|
# Check v6 upgrade guide
|
|
curl -s https://spatie.be/docs/laravel-permission/v6/upgrade
|
|
|
|
# Run migration (if provided)
|
|
php artisan vendor:publish --tag="permissions-migration"
|
|
```
|
|
|
|
**Action:** Test permission system thoroughly after upgrade
|
|
|
|
#### 2.3.3 Laravel Reverb v1 → v2
|
|
|
|
**Expected Changes:**
|
|
- Configuration file changes (`config/reverb.php`)
|
|
- Server connection changes
|
|
- Event broadcasting changes
|
|
- Presence channel changes
|
|
|
|
**Migration Steps:**
|
|
```bash
|
|
composer show beyondcode/laravel-reverb
|
|
curl -s https://reverb.laravel.com/docs/2.x/upgrade
|
|
```
|
|
|
|
**Action:** Verify Reverb server configuration and reconnection
|
|
|
|
#### 2.3.4 Laravel Scout v10 → v11
|
|
|
|
**Expected Changes:**
|
|
- Index configuration changes
|
|
- Model preparation changes
|
|
- Search query changes
|
|
- Elasticsearch client changes
|
|
|
|
**Migration Steps:**
|
|
```bash
|
|
composer show laravel/scout
|
|
curl -s https://laravel.com/docs/12.x/scout
|
|
```
|
|
|
|
**Action:** Rebuild all Elasticsearch indices after upgrade
|
|
|
|
#### 2.3.5 Other Dependencies
|
|
|
|
**Full Dependency Upgrade List:**
|
|
```
|
|
┌──────────────────────────┬──────────────┬──────────────┬─────────────┬─────────────────┐
|
|
│ Package │ Current │ Target │ Risk │ Migration Notes │
|
|
├──────────────────────────┼──────────────┼──────────────┼─────────────┼─────────────────┤
|
|
│ laravel/framework │ 11.57.0 │ 12.x │ HIGH │ Core framework │
|
|
│ livewire/livewire │ 3.8.0 │ 4.0 │ HIGH │ Major version │
|
|
│ spatie/laravel-permission │ ^5.11 │ ^6.0 │ HIGH │ Major version │
|
|
│ beyondcode/laravel-reverb │ ^1.0 │ ^2.0 │ MEDIUM │ Major version │
|
|
│ laravel/scout │ ^10.0 │ ^11.0 │ MEDIUM │ Major version │
|
|
│ cyrildev/laravel-love │ ^4.0 │ Latest │ LOW │ Minor update │
|
|
│ namu/wire-chat │ ^0.2.11 │ Latest │ LOW │ Check compat │
|
|
│ wire-elements/wire-elements│ ^3.0 │ Latest │ LOW │ Check compat │
|
|
│ laravel/jetstream │ ^4.0 │ Latest │ LOW │ Check compat │
|
|
│ wireui/wireui │ ^2.5 │ Latest │ LOW │ Check compat │
|
|
│ tailwindcss/tailwindcss │ ^3.x │ Latest │ LOW │ No changes │
|
|
│ alpinejs/alpinejs │ ^3.13 │ Latest │ LOW │ No changes │
|
|
└──────────────────────────┴──────────────┴──────────────┴─────────────┴─────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🏗️ PART 3: DETAILED UPGRADE STRATEGY
|
|
|
|
### 3.1 Phase 0: Research & Documentation (1-2 hours)
|
|
|
|
**Goal:** Understand all changes before touching any code
|
|
|
|
#### 3.1.1 Laravel 12 Release Notes
|
|
```bash
|
|
# When Laravel 12 is released, download and analyze
|
|
curl -s https://laravel.com/docs/12.x/upgrade > laravel-12-upgrade-guide.md
|
|
curl -s https://laravel.com/docs/12.x/release-notes > laravel-12-release-notes.md
|
|
|
|
# Extract all breaking changes
|
|
grep -E "## Breaking Changes|### |- " laravel-12-upgrade-guide.md > breaking-changes-summary.md
|
|
```
|
|
|
|
#### 3.1.2 Dependency Upgrade Guides
|
|
```bash
|
|
# Create a directory for all upgrade guides
|
|
mkdir -p .agents/memory/upgrade-guides
|
|
cd .agents/memory/upgrade-guides
|
|
|
|
# Download all relevant upgrade guides
|
|
curl -s https://laravel.com/docs/12.x/upgrade -o laravel-12-upgrade.md
|
|
curl -s https://laravel-livewire.com/docs/4.x/upgrade-guide -o livewire-4-upgrade.md
|
|
curl -s https://spatie.be/docs/laravel-permission/v6/upgrade -o spatie-permissions-6-upgrade.md
|
|
curl -s https://reverb.laravel.com/docs/2.x/upgrade -o reverb-2-upgrade.md
|
|
curl -s https://laravel.com/docs/12.x/scout -o scout-11-upgrade.md
|
|
```
|
|
|
|
#### 3.1.3 Create Change Impact Matrix
|
|
**Document:** `.agents/memory/laravel12_change_impact_matrix.md`
|
|
|
|
```markdown
|
|
# Laravel 12 Change Impact Matrix
|
|
|
|
## High Impact (Must Review)
|
|
| Change | Affects | Action | Owner |
|
|
|--------|---------|--------|-------|
|
|
| PHP 8.3+ requirement | All servers | Verify PHP version | User |
|
|
| Livewire 4.0 | All Livewire components | Manual migration | Vibe |
|
|
| Spatie v6 | Permission system | Manual migration | Vibe |
|
|
|
|
## Medium Impact (Likely Affects)
|
|
| Change | Affects | Action | Owner |
|
|
|--------|---------|--------|-------|
|
|
| Service provider changes | bootstrap/ | Review config | Vibe |
|
|
| Route changes | routes/ | Test all routes | Both |
|
|
|
|
## Low Impact (Minimal)
|
|
| Change | Affects | Action | Owner |
|
|
|--------|---------|--------|-------|
|
|
| Blade directive changes | views/ | Find/replace | Vibe |
|
|
```
|
|
|
|
#### 3.1.4 Create File-by-File Upgrade Plan
|
|
**Document:** `.agents/memory/laravel12_file_upgrade_plan.md`
|
|
|
|
```bash
|
|
# Generate list of all PHP files that may need changes
|
|
cd /home/r/Websites/timebank_cc_2
|
|
|
|
# Find all files that import Laravel classes
|
|
find . -type f -name "*.php" -exec grep -l "use Illuminate\\" {} \; | grep -v vendor | grep -v node_modules > laravel-dependents.txt
|
|
|
|
# Find all files that use Laravel facades
|
|
find . -type f -name "*.php" -exec grep -l "\\\\Facades\\\\" {} \; | grep -v vendor | grep -v node_modules >> laravel-dependents.txt
|
|
|
|
# Find all config files
|
|
find config -type f -name "*.php" > config-files.txt
|
|
|
|
# Sort and deduplicate
|
|
sort -u laravel-dependents.txt config-files.txt > files-to-review.txt
|
|
```
|
|
|
|
### 3.2 Phase 1: Environment Preparation (1 hour)
|
|
|
|
#### 3.2.1 PHP 8.3+ Verification
|
|
```bash
|
|
# Local machine
|
|
php -v | grep -E "PHP 8\.3|PHP 8\.4"
|
|
|
|
# Development server
|
|
ssh dev "php -v | grep -E 'PHP 8\.3|PHP 8\.4'"
|
|
|
|
# Production server
|
|
ssh prod "php -v | grep -E 'PHP 8\.3|PHP 8\.4'"
|
|
|
|
# If PHP 8.2 is found, upgrade instructions:
|
|
# Ubuntu/Debian:
|
|
sudo apt-get install software-properties-common
|
|
sudo add-apt-repository ppa:ondrej/php -y
|
|
sudo apt-get update
|
|
sudo apt-get install php8.3 php8.3-fpm php8.3-cli php8.3-common -y
|
|
sudo a2enmod php8.3
|
|
sudo systemctl restart apache2
|
|
```
|
|
|
|
#### 3.2.2 Composer Requirements Check
|
|
```bash
|
|
# Check current PHP requirement in composer.json
|
|
grep -A2 '"php"' composer.json
|
|
|
|
# Update to PHP 8.3+
|
|
# Edit composer.json:
|
|
# "require": {
|
|
# "php": "^8.3",
|
|
# ...
|
|
# }
|
|
|
|
# Verify all dependencies support PHP 8.3+
|
|
composer why-not php:8.3 2>/dev/null || echo "All deps support PHP 8.3+"
|
|
```
|
|
|
|
#### 3.2.3 Backup Strategy
|
|
```bash
|
|
# Create comprehensive backup script
|
|
cat > scripts/backup-for-laravel12.sh << 'EOF'
|
|
#!/bin/bash
|
|
set -e
|
|
|
|
STAMP=$(date +%Y%m%d-%H%M%S)
|
|
BACKUP_DIR="storage/app/upgrades/laravel11-to-12-$STAMP"
|
|
|
|
echo "Creating backup in $BACKUP_DIR..."
|
|
|
|
# Create directory
|
|
mkdir -p "$BACKUP_DIR"
|
|
|
|
# 1. Git state backup
|
|
git bundle create "$BACKUP_DIR/git-state.bundle" --all
|
|
git rev-parse HEAD > "$BACKUP_DIR/current-commit.txt"
|
|
git status --short > "$BACKUP_DIR/git-status.txt"
|
|
|
|
# 2. Database backup
|
|
if [ -f scripts/backup-database.sh ]; then
|
|
echo "Backing up database..."
|
|
bash scripts/backup-database.sh
|
|
cp backups/*.sql.gz "$BACKUP_DIR/" 2>/dev/null || true
|
|
else
|
|
echo "No backup-database.sh found, skipping database backup"
|
|
fi
|
|
|
|
# 3. Vendor backup
|
|
echo "Backing up vendor..."
|
|
tar -czf "$BACKUP_DIR/vendor.tar.gz" vendor/ 2>/dev/null || echo "⚠ Vendor backup skipped"
|
|
|
|
# 4. Public/build backup
|
|
echo "Backing up public/build..."
|
|
tar -czf "$BACKUP_DIR/public-build.tar.gz" public/build/ 2>/dev/null || echo "⚠ Public/build backup skipped"
|
|
|
|
# 5. Storage backup (except backups and upgrades)
|
|
echo "Backing up storage..."
|
|
tar -czf "$BACKUP_DIR/storage.tar.gz" storage/ --exclude="storage/app/backups" --exclude="storage/app/upgrades" 2>/dev/null || echo "⚠ Storage backup skipped"
|
|
|
|
# 6. .env backup
|
|
cp .env "$BACKUP_DIR/.env.backup"
|
|
|
|
# 7. Composer files
|
|
cp composer.json composer.lock "$BACKUP_DIR/"
|
|
|
|
# 8. NPM files
|
|
cp package.json package-lock.json "$BACKUP_DIR/" 2>/dev/null || true
|
|
|
|
echo "✓ Backup complete in $BACKUP_DIR"
|
|
EOF
|
|
|
|
chmod +x scripts/backup-for-laravel12.sh
|
|
```
|
|
|
|
#### 3.2.4 Create Rollback Script
|
|
```bash
|
|
cat > scripts/rollback-laravel12.sh << 'EOF'
|
|
#!/bin/bash
|
|
# Rollback from Laravel 12 to Laravel 11
|
|
|
|
STAMP=$1
|
|
BACKUP_DIR="storage/app/upgrades/laravel11-to-12-$STAMP"
|
|
|
|
if [ -z "$STAMP" ]; then
|
|
# Find latest backup
|
|
STAMP=$(ls -td storage/app/upgrades/laravel11-to-12-* | head -1 | basename)
|
|
BACKUP_DIR="storage/app/upgrades/$STAMP"
|
|
fi
|
|
|
|
echo "Rolling back using backup: $BACKUP_DIR"
|
|
|
|
# 1. Maintenance mode
|
|
php artisan down --retry=60 --secret=rollback-$(date +%s | tail -c 8)
|
|
|
|
# 2. Restore git state
|
|
cd /home/r/Websites/timebank_cc_2
|
|
git fetch origin
|
|
git checkout main
|
|
git pull origin main
|
|
|
|
# 3. Restore vendor
|
|
rm -rf vendor/
|
|
if [ -f "$BACKUP_DIR/vendor.tar.gz" ]; then
|
|
tar -xzf "$BACKUP_DIR/vendor.tar.gz" -C .
|
|
fi
|
|
|
|
# 4. Restore public/build
|
|
rm -rf public/build/
|
|
if [ -f "$BACKUP_DIR/public-build.tar.gz" ]; then
|
|
tar -xzf "$BACKUP_DIR/public-build.tar.gz" -C .
|
|
fi
|
|
|
|
# 5. Restore .env
|
|
if [ -f "$BACKUP_DIR/.env.backup" ]; then
|
|
cp "$BACKUP_DIR/.env.backup" .env
|
|
fi
|
|
|
|
# 6. Clear caches
|
|
php artisan optimize:clear
|
|
php artisan config:clear
|
|
php artisan cache:clear
|
|
php artisan view:clear
|
|
php artisan route:clear
|
|
php artisan event:clear
|
|
|
|
# 7. Install dependencies
|
|
composer install --no-dev --no-interaction
|
|
|
|
# 8. Restart services
|
|
echo "Please restart these services manually:"
|
|
echo " sudo systemctl restart apache2 (or nginx)"
|
|
echo " sudo systemctl restart php8.3-fpm"
|
|
echo " sudo systemctl restart timebank-*"
|
|
|
|
# 9. Bring site up
|
|
php artisan up
|
|
|
|
echo "✓ Rollback complete"
|
|
EOF
|
|
|
|
chmod +x scripts/rollback-laravel12.sh
|
|
```
|
|
|
|
### 3.3 Phase 2: Dependency Upgrades (2-4 hours)
|
|
|
|
#### 3.3.1 Upgrade Laravel Framework
|
|
```bash
|
|
# First, create a test branch
|
|
git checkout -b laravel-12-upgrade-test origin/laravel-11
|
|
|
|
# Update Laravel Framework
|
|
composer require laravel/framework:^12.0 --no-interaction --no-progress
|
|
|
|
# This will update many dependencies
|
|
# Review the changes carefully
|
|
```
|
|
|
|
#### 3.3.2 Upgrade Livewire
|
|
```bash
|
|
# Check current version
|
|
composer show livewire/livewire
|
|
|
|
# Try to upgrade to 4.0
|
|
composer require livewire/livewire:^4.0 --no-interaction --no-progress 2>/dev/null || \
|
|
echo "Livewire 4.0 not available yet, keeping 3.8"
|
|
|
|
# If Livewire 4.0 is required, we may need to wait
|
|
# Or use a dev version: composer require livewire/livewire:4.x-dev
|
|
```
|
|
|
|
#### 3.3.3 Upgrade Spatie Permissions
|
|
```bash
|
|
# Check current version
|
|
composer show spatie/laravel-permission
|
|
|
|
# Upgrade to v6
|
|
composer require spatie/laravel-permission:^6.0 --no-interaction --no-progress
|
|
|
|
# After upgrade, run any migrations
|
|
php artisan vendor:publish --tag="permissions-migrations" 2>/dev/null || true
|
|
php artisan migrate --force 2>/dev/null || true
|
|
```
|
|
|
|
#### 3.3.4 Upgrade Other Dependencies
|
|
```bash
|
|
# Reverb
|
|
composer require beyondcode/laravel-reverb:^2.0 --no-interaction --no-progress
|
|
|
|
# Scout
|
|
composer require laravel/scout:^11.0 --no-interaction --no-progress
|
|
|
|
# Update all other dependencies
|
|
composer update --no-interaction --no-progress
|
|
```
|
|
|
|
#### 3.3.5 Verify Composer Install
|
|
```bash
|
|
# Install all dependencies
|
|
composer install --no-dev --no-interaction
|
|
|
|
# Check for conflicts
|
|
composer why-not laravel/framework:^12.0
|
|
composer why-not livewire/livewire:^4.0
|
|
```
|
|
|
|
### 3.4 Phase 3: Code Changes (2-4 hours)
|
|
|
|
#### 3.4.1 Apply Laravel Core Changes
|
|
**For each breaking change in Laravel 12, apply fixes:**
|
|
|
|
**Example: Service Provider Changes**
|
|
```php
|
|
// Laravel 11: app/Providers/AppServiceProvider.php
|
|
public function register()
|
|
{
|
|
// Old code
|
|
}
|
|
|
|
// Laravel 12: app/Providers/AppServiceProvider.php
|
|
public function register()
|
|
{
|
|
// New code - check upgrade guide for specific changes
|
|
}
|
|
```
|
|
|
|
**Action:** Create migration scripts for each change type
|
|
|
|
#### 3.4.2 Livewire 4.0 Migration
|
|
**Detailed Migration Steps:**
|
|
|
|
1. **Syntax Changes:**
|
|
```bash
|
|
# Find all @entangle directives
|
|
grep -r "@entangle" resources/views/ --include="*.blade.php" > livewire-entangle-uses.txt
|
|
|
|
# Find all wire:model directives
|
|
grep -r "wire:model" resources/views/ --include="*.blade.php" > livewire-model-uses.txt
|
|
```
|
|
|
|
2. **Component Changes:**
|
|
```bash
|
|
# Find all Livewire components
|
|
find app/Http/Livewire -type f -name "*.php" > livewire-components.txt
|
|
|
|
# For each component, check for breaking changes
|
|
while read component; do
|
|
echo "Checking $component..."
|
|
# Add specific checks here
|
|
done < livewire-components.txt
|
|
```
|
|
|
|
3. **JavaScript Changes:**
|
|
```bash
|
|
# Check wire-elements
|
|
grep -r "wire-elements" resources/views/ --include="*.blade.php"
|
|
|
|
# Check Alpine.js usage
|
|
grep -r "x-" resources/views/ --include="*.blade.php" | head -20
|
|
```
|
|
|
|
**Migration Script:** `scripts/migrate-livewire-to-4.sh`
|
|
```bash
|
|
#!/bin/bash
|
|
# Livewire 3.8 to 4.0 migration script
|
|
|
|
echo "Migrating Livewire from 3.8 to 4.0..."
|
|
|
|
# 1. Update Blade directives
|
|
find resources/views -name "*.blade.php" -exec sed -i 's/@entangle(/@modelable(/g' {} \;
|
|
find resources/views -name "*.blade.php" -exec sed -i 's/wire:model=/wire:model.live=/g' {} \;
|
|
|
|
# 2. Update component namespace (if needed)
|
|
# This is just an example - actual changes depend on Livewire 4.0 guide
|
|
|
|
# 3. Update config/livewire.php
|
|
# Check for deprecated options
|
|
|
|
# 4. Clear Livewire cache
|
|
php artisan livewire:discover
|
|
php artisan view:clear
|
|
|
|
echo "✓ Livewire migration script created (TEST FIRST!)"
|
|
```
|
|
|
|
#### 3.4.3 Spatie Permissions Migration
|
|
**Migration Script:** `scripts/migrate-spatie-to-6.sh`
|
|
```bash
|
|
#!/bin/bash
|
|
# Spatie Permissions v5 to v6 migration
|
|
|
|
echo "Migrating Spatie Permissions from v5 to v6..."
|
|
|
|
# 1. Check for deprecated method calls
|
|
# grep -r "hasRole\|hasPermission\|givePermissionTo\|assignRole" app/ --include="*.php" > spatie-usage.txt
|
|
|
|
# 2. Update any deprecated methods
|
|
# Based on Spatie v6 upgrade guide
|
|
|
|
# 3. Sync all permissions
|
|
php artisan permission:sync 2>/dev/null || echo "No permission:sync command"
|
|
|
|
# 4. Test permission system
|
|
php artisan tinker --execute="
|
|
\$user = App\\Models\\User::first();
|
|
if (\$user) {
|
|
echo 'Testing user: ' . \$user->id . '\\n';
|
|
echo 'Roles: ' . json_encode(\$user->getRoleNames()) . '\\n';
|
|
echo 'Permissions: ' . json_encode(\$user->getAllPermissions()->pluck('name')) . '\\n';
|
|
echo '✓ Permission system working\\n';
|
|
} else {
|
|
echo '⚠ No user found\\n';
|
|
}
|
|
"
|
|
|
|
echo "✓ Spatie migration complete"
|
|
```
|
|
|
|
#### 3.4.4 Multi-Guard Authentication Verification
|
|
**Test Script:** `scripts/verify-multi-guard.sh`
|
|
```bash
|
|
#!/bin/bash
|
|
# Verify multi-guard authentication after upgrade
|
|
|
|
echo "Verifying multi-guard authentication..."
|
|
|
|
php artisan tinker --execute="
|
|
// Test User model
|
|
\$user = App\\Models\\User::first();
|
|
if (!\$user) {
|
|
echo '❌ No User found\\n';
|
|
exit(1);
|
|
}
|
|
echo '✓ User model loads\\n';
|
|
|
|
// Test Organization model
|
|
\$org = App\\Models\\Organization::first();
|
|
if (!\$org) {
|
|
echo '⚠ No Organization found (may be OK)\\n';
|
|
} else {
|
|
echo '✓ Organization model loads\\n';
|
|
}
|
|
|
|
// Test Bank model
|
|
\$bank = App\\Models\\Bank::first();
|
|
if (!\$bank) {
|
|
echo '⚠ No Bank found (may be OK)\\n';
|
|
} else {
|
|
echo '✓ Bank model loads\\n';
|
|
}
|
|
|
|
// Test Admin model
|
|
\$admin = App\\Models\\Admin::first();
|
|
if (!\$admin) {
|
|
echo '⚠ No Admin found (may be OK)\\n';
|
|
} else {
|
|
echo '✓ Admin model loads\\n';
|
|
}
|
|
|
|
// Test guard configuration
|
|
\$guards = config('auth.guards');
|
|
if (isset(\$guards['web']) && isset(\$guards['organization']) && isset(\$guards['bank']) && isset(\$guards['admin'])) {
|
|
echo '✓ All 4 guards configured\\n';
|
|
} else {
|
|
echo '❌ Missing guards in config\\n';
|
|
exit(1);
|
|
}
|
|
|
|
// Test SwitchGuardTrait
|
|
if (class_exists('App\\\\Traits\\\\SwitchGuardTrait')) {
|
|
echo '✓ SwitchGuardTrait exists\\n';
|
|
} else {
|
|
echo '❌ SwitchGuardTrait missing\\n';
|
|
exit(1);
|
|
}
|
|
|
|
echo '✓ Multi-guard authentication verification complete\\n';
|
|
"
|
|
```
|
|
|
|
#### 3.4.5 Two-Layer Permission System Verification
|
|
**Test Script:** `scripts/verify-permissions.sh`
|
|
```bash
|
|
#!/bin/bash
|
|
# Verify two-layer permission system after upgrade
|
|
|
|
echo "Verifying two-layer permission system..."
|
|
|
|
php artisan tinker --execute="
|
|
// 1. Check admin_roles table
|
|
\$adminRoles = App\\Models\\AdminRole::count();
|
|
echo 'AdminRoles count: ' . \$adminRoles . '\\n';
|
|
|
|
// 2. Check organization_roles table
|
|
\$orgRoles = App\\Models\\OrganizationRole::count();
|
|
echo 'OrganizationRoles count: ' . \$orgRoles . '\\n';
|
|
|
|
// 3. Check Spatie roles
|
|
\$spatieRoles = Spatie\\Permission\\Models\\Role::count();
|
|
echo 'Spatie Roles count: ' . \$spatieRoles . '\\n';
|
|
|
|
// 4. Test sync for a specific role
|
|
\$adminRole = App\\Models\\AdminRole::first();
|
|
if (\$adminRole) {
|
|
\$suffix = '\\\\' . \$adminRole->name;
|
|
\$spatieRoles = Spatie\\Permission\\Models\\Role::where('guard_name', 'web')
|
|
->where('name', 'like', '%' . \$suffix)
|
|
->get();
|
|
|
|
if (\$spatieRoles->isEmpty()) {
|
|
echo '⚠ No Spatie roles found for AdminRole: ' . \$adminRole->name . '\\n';
|
|
} else {
|
|
echo '✓ Spatie roles found for AdminRole: ' . \$adminRole->name . '\\n';
|
|
|
|
// Check if permissions match
|
|
\$role = \$spatieRoles->first();
|
|
\$adminPerms = \$adminRole->permissions ?? [];
|
|
\$spatiePerms = \$role->permissions->pluck('name')->toArray();
|
|
|
|
if (sort(\$adminPerms) === sort(\$spatiePerms)) {
|
|
echo '✓ Permissions synced for this role\\n';
|
|
} else {
|
|
echo '⚠ Permission mismatch for ' . \$adminRole->name . '\\n';
|
|
echo ' AdminRole: ' . json_encode(\$adminPerms) . '\\n';
|
|
echo ' Spatie: ' . json_encode(\$spatiePerms) . '\\n';
|
|
}
|
|
}
|
|
} else {
|
|
echo '⚠ No AdminRole found\\n';
|
|
}
|
|
|
|
// 5. Test permission checking
|
|
\$user = App\\Models\\User::first();
|
|
if (\$user) {
|
|
// Build a test role name
|
|
\$testRole = 'Admin\\\\1\\\\admin'; // Example for profile 1
|
|
if (\$user->hasRole(\$testRole)) {
|
|
echo '✓ User role checking works\\n';
|
|
} else {
|
|
echo '⚠ User does not have test role (may be OK)\\n';
|
|
}
|
|
} else {
|
|
echo '⚠ No User found for permission test\\n';
|
|
}
|
|
|
|
echo '✓ Two-layer permission system verification complete\\n';
|
|
"
|
|
```
|
|
|
|
#### 3.4.6 White-Label Configuration Verification
|
|
**Test Script:** `scripts/verify-white-label.sh`
|
|
```bash
|
|
#!/bin/bash
|
|
# Verify white-label configuration system after upgrade
|
|
|
|
echo "Verifying white-label configuration..."
|
|
|
|
php artisan tinker --execute="
|
|
// Test timebank_config helper
|
|
\$platformName = timebank_config('platform_name');
|
|
echo 'Platform name: ' . \$platformName . '\\n';
|
|
|
|
// Test currency config
|
|
\$currency = timebank_config('currency_name_singular');
|
|
echo 'Currency singular: ' . \$currency . '\\n';
|
|
|
|
// Test all config files
|
|
\$configFiles = glob('config/timebank*.php');
|
|
echo 'Platform config files: ' . json_encode(\$configFiles) . '\\n';
|
|
|
|
// Test config merge
|
|
Artisan::call('config:merge --all --dry-run');
|
|
\$output = Artisan::output();
|
|
if (str_contains(\$output, 'new keys available')) {
|
|
echo '⚠ New config keys available (expected during upgrade):\\n' . \$output . '\\n';
|
|
} else {
|
|
echo '✓ Config merge clean\\n';
|
|
}
|
|
|
|
// Test theme helper
|
|
\$themeColor = theme_color('primary.500');
|
|
echo 'Theme primary.500: ' . \$themeColor . '\\n';
|
|
|
|
echo '✓ White-label configuration verification complete\\n';
|
|
"
|
|
```
|
|
|
|
### 3.5 Phase 4: Testing (4-8 hours)
|
|
|
|
#### 3.5.1 Automated Test Suite
|
|
```bash
|
|
# Run all tests
|
|
echo "Running full test suite..."
|
|
php artisan test --log-junit --log-file=tests/laravel12-upgrade-tests.xml
|
|
|
|
# Run specific test suites
|
|
echo "Running authentication tests..."
|
|
php artisan test --filter AuthenticationTest
|
|
|
|
echo "Running authorization tests..."
|
|
php artisan test --filter AuthorizationTest 2>/dev/null || echo "No AuthorizationTest found"
|
|
|
|
echo "Running profile tests..."
|
|
php artisan test --filter Profile 2>/dev/null || echo "No Profile tests found"
|
|
|
|
echo "Running security tests..."
|
|
php artisan test --filter SearchXssProtectionTest
|
|
php artisan test --filter PostContentXssProtectionTest
|
|
```
|
|
|
|
#### 3.5.2 Manual Testing Matrix
|
|
|
|
**Test Suite: Authentication & Profiles**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ User registration │ HIGH │ ⬜ │ manual │
|
|
│ User login/logout │ HIGH │ ⬜ │ manual │
|
|
│ Organization profile creation │ HIGH │ ⬜ │ manual │
|
|
│ Bank profile creation │ HIGH │ ⬜ │ manual │
|
|
│ Admin profile creation │ HIGH │ ⬜ │ manual │
|
|
│ Switch from User to Organization │ HIGH │ ⬜ │ verify-multi-guard.sh │
|
|
│ Switch from User to Bank │ HIGH │ ⬜ │ verify-multi-guard.sh │
|
|
│ Switch from User to Admin │ HIGH │ ⬜ │ verify-multi-guard.sh │
|
|
│ Switch back to User │ HIGH │ ⬜ │ verify-multi-guard.sh │
|
|
│ Session persistence │ HIGH │ ⬜ │ manual │
|
|
│ Presence tracking │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Permissions**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ Admin access to admin features │ HIGH │ ⬜ │ verify-permissions.sh │
|
|
│ Organization manager permissions │ HIGH │ ⬜ │ verify-permissions.sh │
|
|
│ Bank manager permissions │ HIGH │ ⬜ │ verify-permissions.sh │
|
|
│ Role creation │ MEDIUM │ ⬜ │ manual │
|
|
│ Role editing │ MEDIUM │ ⬜ │ manual │
|
|
│ Role deletion │ MEDIUM │ ⬜ │ manual │
|
|
│ Permission inheritance │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Transactions**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ User creates payment │ HIGH │ ⬜ │ manual │
|
|
│ Transaction recorded correctly │ HIGH │ ⬜ │ manual │
|
|
│ Balance updated correctly │ HIGH │ ⬜ │ manual │
|
|
│ Transaction immutability │ HIGH │ ⬜ │ manual │
|
|
│ Calls paused at zero credits │ MEDIUM │ ⬜ │ manual │
|
|
│ Transaction history │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Messaging**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ Chat message between users │ HIGH │ ⬜ │ manual │
|
|
│ Image upload in chat │ HIGH │ ⬜ │ manual │
|
|
│ Message delivery │ HIGH │ ⬜ │ manual │
|
|
│ Message read receipts │ MEDIUM │ ⬜ │ manual │
|
|
│ Chat with multiple participants │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Search**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ Elasticsearch indexing │ HIGH │ ⬜ │ manual │
|
|
│ Search returns results │ HIGH │ ⬜ │ manual │
|
|
│ Search boost factors │ MEDIUM │ ⬜ │ manual │
|
|
│ Multi-language search (en) │ MEDIUM │ ⬜ │ manual │
|
|
│ Multi-language search (nl) │ MEDIUM │ ⬜ │ manual │
|
|
│ Multi-language search (de) │ MEDIUM │ ⬜ │ manual │
|
|
│ Multi-language search (es) │ MEDIUM │ ⬜ │ manual │
|
|
│ Multi-language search (fr) │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Configuration & Themes**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ timebank_config() helper │ HIGH │ ⬜ │ verify-white-label.sh │
|
|
│ White-label platform configs │ HIGH │ ⬜ │ verify-white-label.sh │
|
|
│ Theme: timebank_cc │ HIGH │ ⬜ │ manual │
|
|
│ Theme: uuro │ HIGH │ ⬜ │ manual │
|
|
│ Theme: vegetable │ HIGH │ ⬜ │ manual │
|
|
│ Theme: yellow │ HIGH │ ⬜ │ manual │
|
|
│ Footer navigation │ MEDIUM │ ⬜ │ manual │
|
|
│ Local pages configuration │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
**Test Suite: Background Processes**
|
|
```
|
|
┌─────────────────────────────────┬──────────┬────────┬──────────────┐
|
|
│ Test Case │ Priority │ Status │ Test Script │
|
|
├─────────────────────────────────┼──────────┼────────┼──────────────┤
|
|
│ Queue worker starts │ HIGH │ ⬜ │ manual │
|
|
│ Queue worker processes jobs │ HIGH │ ⬜ │ manual │
|
|
│ Reverb WebSocket server starts │ HIGH │ ⬜ │ manual │
|
|
│ Presence tracking updates │ MEDIUM │ ⬜ │ manual │
|
|
│ Scheduled tasks run │ MEDIUM │ ⬜ │ manual │
|
|
└─────────────────────────────────┴──────────┴────────┴──────────────┘
|
|
```
|
|
|
|
#### 3.5.3 Performance Testing
|
|
|
|
**Load Testing:**
|
|
```bash
|
|
# Simulate 100 concurrent users
|
|
ab -n 100 -c 10 http://localhost:8000/
|
|
|
|
# Check memory usage
|
|
php artisan tinker --execute="
|
|
\$memory = memory_get_usage() / 1024 / 1024;
|
|
echo 'Memory usage: ' . round(\$memory, 2) . ' MB' . PHP_EOL;
|
|
"
|
|
|
|
# Check page load times
|
|
curl -o /dev/null -s -w "%{time_total}s" http://localhost:8000/
|
|
```
|
|
|
|
**Queue Performance:**
|
|
```bash
|
|
# Time a job
|
|
php artisan queue:work --once --queue=default --time
|
|
|
|
# Check queue lag
|
|
php artisan tinker --execute="
|
|
\$lag = \App\Jobs\SomeJob::getQueueLag();
|
|
echo 'Queue lag: ' . \$lag . ' seconds' . PHP_EOL;
|
|
" 2>/dev/null || echo "No queue lag method"
|
|
```
|
|
|
|
**Search Performance:**
|
|
```bash
|
|
# Time a search query
|
|
php artisan tinker --execute="
|
|
\$start = microtime(true);
|
|
\$results = \App\Models\Post::search('test')->get();
|
|
\$time = microtime(true) - \$start;
|
|
echo 'Search time: ' . round(\$time * 1000) . 'ms' . PHP_EOL;
|
|
echo 'Results: ' . count(\$results) . PHP_EOL;
|
|
"
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 PART 4: UPGRADE EXECUTION PLAN
|
|
|
|
### 4.1 Option A: Automated Upgrade (Recommended)
|
|
|
|
**Following the pattern from Laravel 10→11 upgrade:**
|
|
|
|
#### 4.1.1 Create Upgrade Script
|
|
```bash
|
|
# Get the latest upgrade.sh template from laravel-12 branch
|
|
git fetch origin
|
|
git show origin/laravel-12:scripts/upgrade-to-12.sh > /tmp/upgrade-to-12.sh
|
|
|
|
# Review and customize it
|
|
nano /tmp/upgrade-to-12.sh
|
|
|
|
# Make executable
|
|
chmod +x /tmp/upgrade-to-12.sh
|
|
```
|
|
|
|
#### 4.1.2 Dry Run on Test Server
|
|
```bash
|
|
# SSH to test server
|
|
ssh test-server
|
|
|
|
# Run dry run
|
|
tmux new -s laravel12-dry-run
|
|
cd /var/www/timebank_cc_test
|
|
bash /tmp/upgrade-to-12.sh --dry-run --target origin/laravel-12
|
|
```
|
|
|
|
#### 4.1.3 Actual Upgrade on Test Server
|
|
```bash
|
|
tmux new -s laravel12-upgrade
|
|
cd /var/www/timebank_cc_test
|
|
bash /tmp/upgrade-to-12.sh --target origin/laravel-12
|
|
```
|
|
|
|
#### 4.1.4 Testing on Test Server
|
|
```bash
|
|
# Run all tests
|
|
php artisan test
|
|
|
|
# Manual testing (use the test matrix above)
|
|
# Document any issues in: .agents/memory/laravel12_test_issues.md
|
|
```
|
|
|
|
#### 4.1.5 Fix Issues on Test Server
|
|
```bash
|
|
# For each issue found:
|
|
# 1. Document in WORKLOG.md
|
|
# 2. Create fix in app/ code
|
|
# 3. Test fix
|
|
# 4. Commit fix to laravel-12 branch
|
|
```
|
|
|
|
#### 4.1.6 Upgrade Staging Server
|
|
```bash
|
|
ssh staging-server
|
|
tmux new -s laravel12-upgrade
|
|
cd /var/www/timebank_cc_staging
|
|
bash /tmp/upgrade-to-12.sh --target origin/laravel-12
|
|
```
|
|
|
|
#### 4.1.7 Testing on Staging Server
|
|
```bash
|
|
# Full test suite
|
|
php artisan test
|
|
|
|
# Manual testing
|
|
# Verify all critical paths
|
|
```
|
|
|
|
#### 4.1.8 Production Upgrade
|
|
```bash
|
|
# During low-traffic period (e.g., 2-4 AM)
|
|
ssh prod-server
|
|
tmux new -s laravel12-upgrade-prod
|
|
cd /var/www/timebank_cc
|
|
|
|
# Notify monitoring
|
|
# Run upgrade
|
|
bash /tmp/upgrade-to-12.sh --target origin/laravel-12
|
|
|
|
# Monitor for 1 hour
|
|
# Verify all critical paths
|
|
```
|
|
|
|
### 4.2 Option B: Manual Step-by-Step Upgrade
|
|
|
|
**For more control, use manual steps:**
|
|
|
|
#### Step 1: Backup Everything
|
|
```bash
|
|
scripts/backup-for-laravel12.sh
|
|
```
|
|
|
|
#### Step 2: Update Composer
|
|
```bash
|
|
composer require laravel/framework:^12.0
|
|
composer require livewire/livewire:^4.0
|
|
composer require spatie/laravel-permission:^6.0
|
|
composer require beyondcode/laravel-reverb:^2.0
|
|
composer require laravel/scout:^11.0
|
|
composer update
|
|
```
|
|
|
|
#### Step 3: Update Code
|
|
```bash
|
|
# Apply all code changes identified in Phase 3
|
|
# Run migration scripts
|
|
bash scripts/migrate-livewire-to-4.sh
|
|
bash scripts/migrate-spatie-to-6.sh
|
|
```
|
|
|
|
#### Step 4: Run Deploy
|
|
```bash
|
|
bash deploy.sh -m -n # Skip migrations and npm initially
|
|
bash deploy.sh # Full deploy after verification
|
|
```
|
|
|
|
#### Step 5: Test
|
|
```bash
|
|
php artisan test
|
|
# Manual testing per test matrix
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 PART 5: DEPLOYMENT PLAN
|
|
|
|
### 5.1 Deployment Order
|
|
|
|
**Recommended Order:**
|
|
1. **Local Development** - First, for quick iteration
|
|
2. **Test Server** - Full test suite + manual testing
|
|
3. **Staging Server** - User acceptance testing
|
|
4. **Production** - During low-traffic window
|
|
|
|
**Timing:**
|
|
- Local: Anytime
|
|
- Test: Anytime
|
|
- Staging: Business hours (for user testing)
|
|
- Production: 2-4 AM (lowest traffic)
|
|
|
|
### 5.2 Deployment Window
|
|
|
|
**Production Deployment:**
|
|
- **Start:** 02:00 AM (low traffic)
|
|
- **Estimated Duration:** 2-4 hours
|
|
- **Expected Downtime:** 15-30 minutes
|
|
- **Maintenance Page:** Yes, with bypass URL
|
|
|
|
**Communication:**
|
|
- Notify users 24 hours before
|
|
- Provide estimated downtime
|
|
- Provide status page URL
|
|
- Notify when complete
|
|
|
|
### 5.3 Rollback Decision Points
|
|
|
|
**Automatic Rollback Triggers:**
|
|
- Upgrade script fails at any step
|
|
- Tests fail with > 5 errors
|
|
- Critical feature broken (login, payments, chat)
|
|
- Performance degraded > 50%
|
|
|
|
**Manual Rollback Decision:**
|
|
- User reports critical issues
|
|
- Monitoring detects errors
|
|
- Queue workers not processing
|
|
- Search not working
|
|
|
|
---
|
|
|
|
## 🛡️ PART 6: ROLLBACK PLAN (DETAILED)
|
|
|
|
### 6.1 Full Rollback
|
|
|
|
**Script:** `scripts/rollback-laravel12.sh`
|
|
|
|
**Manual Steps:**
|
|
```bash
|
|
# 1. Enter maintenance mode
|
|
php artisan down --retry=60 --secret=rollback-$(date +%s | tail -c 8)
|
|
|
|
# 2. Restore git state
|
|
git checkout main
|
|
git pull origin main
|
|
|
|
# 3. Restore vendor
|
|
rm -rf vendor/
|
|
tar -xzf storage/app/upgrades/laravel11-to-12-*/vendor.tar.gz
|
|
|
|
# 4. Restore public/build
|
|
rm -rf public/build/
|
|
tar -xzf storage/app/upgrades/laravel11-to-12-*/public-build.tar.gz
|
|
|
|
# 5. Restore .env
|
|
cp storage/app/upgrades/laravel11-to-12-*/.env.backup .env
|
|
|
|
# 6. Clear all caches
|
|
php artisan optimize:clear
|
|
php artisan config:clear
|
|
php artisan cache:clear
|
|
php artisan view:clear
|
|
php artisan route:clear
|
|
php artisan event:clear
|
|
|
|
# 7. Restore database (if needed)
|
|
# WARNING: This deletes all data since backup
|
|
gzip -dc storage/app/upgrades/laravel11-to-12-*/*.sql.gz | \
|
|
mysql -u [user] -p[password] [database]
|
|
|
|
# 8. Install dependencies
|
|
composer install --no-dev --no-interaction
|
|
|
|
# 9. Restart services
|
|
sudo systemctl restart apache2
|
|
sudo systemctl restart php8.3-fpm
|
|
sudo systemctl restart timebank-*
|
|
|
|
# 10. Bring site up
|
|
php artisan up
|
|
```
|
|
|
|
### 6.2 Partial Rollback (Code Only)
|
|
|
|
**When:** Database changes are acceptable but code has issues
|
|
|
|
```bash
|
|
# 1. Enter maintenance mode
|
|
php artisan down --retry=60 --secret=partial-rollback-$(date +%s | tail -c 8)
|
|
|
|
# 2. Restore git state
|
|
git checkout main
|
|
git pull origin main
|
|
|
|
# 3. Clear caches
|
|
php artisan optimize:clear
|
|
|
|
# 4. Install dependencies
|
|
composer install --no-dev --no-interaction
|
|
|
|
# 5. Restart services
|
|
sudo systemctl restart apache2
|
|
sudo systemctl restart php8.3-fpm
|
|
sudo systemctl restart timebank-*
|
|
|
|
# 6. Bring site up
|
|
php artisan up
|
|
|
|
# Database remains at Laravel 12 state
|
|
# Laravel 11 code will ignore new tables/columns
|
|
```
|
|
|
|
### 6.3 Rollback Verification
|
|
|
|
**After any rollback, verify:**
|
|
```bash
|
|
# Check Laravel version
|
|
php artisan --version
|
|
|
|
# Run smoke tests
|
|
curl -s http://localhost:8000/ | grep -E "Timebank|Platform"
|
|
|
|
# Check error log
|
|
tail -n 50 storage/logs/laravel-$(date +%F).log
|
|
|
|
# Check queue workers
|
|
sudo systemctl status timebank-* --no-pager
|
|
|
|
# Check Reverb
|
|
sudo systemctl status reverb --no-pager 2>/dev/null || true
|
|
```
|
|
|
|
---
|
|
|
|
## 📊 PART 7: SUCCESS CRITERIA & METRICS
|
|
|
|
### 7.1 Technical Success Criteria
|
|
|
|
**Must Pass (All):**
|
|
- [ ] Laravel 12.x installed and running
|
|
- [ ] All composer dependencies compatible
|
|
- [ ] All tests pass (0 errors)
|
|
- [ ] No PHP errors in logs
|
|
- [ ] Queue workers processing jobs
|
|
- [ ] Reverb WebSocket server running
|
|
- [ ] Elasticsearch indices rebuilt and working
|
|
|
|
**Should Pass (95%+):**
|
|
- [ ] All profile types accessible
|
|
- [ ] Profile switching works
|
|
- [ ] Permission system works
|
|
- [ ] Payments work
|
|
- [ ] Chat/messaging works
|
|
- [ ] Search works
|
|
- [ ] All themes work
|
|
- [ ] White-label configs work
|
|
|
|
### 7.2 Functional Success Criteria
|
|
|
|
**User Stories:**
|
|
- [ ] User can register
|
|
- [ ] User can login/logout
|
|
- [ ] User can switch to Organization profile
|
|
- [ ] User can switch to Bank profile
|
|
- [ ] User can switch to Admin profile
|
|
- [ ] User can create a payment
|
|
- [ ] User can send a chat message
|
|
- [ ] User can search for posts
|
|
- [ ] User can view their profile
|
|
- [ ] Admin can manage users
|
|
- [ ] Organization manager can manage organization
|
|
- [ ] Bank manager can manage bank
|
|
|
|
### 7.3 Performance Success Criteria
|
|
|
|
**Targets:**
|
|
| Metric | Current (Laravel 11) | Target (Laravel 12) | Measured By |
|
|
|--------|----------------------|---------------------|-------------|
|
|
| Page load time | < 1.5s | < 2.0s | ab -n 100 |
|
|
| Memory usage | < 200MB | < 256MB | memory_get_usage() |
|
|
| Queue processing | < 1 min lag | < 1 min lag | Queue monitor |
|
|
| Search queries | < 500ms | < 1000ms | Timer |
|
|
| Concurrent users | 1000 | 1000+ | Load test |
|
|
|
|
---
|
|
|
|
## 📅 PART 8: DETAILED TIMELINE & RESOURCE PLAN
|
|
|
|
### 8.1 Hour-by-Hour Execution Plan
|
|
|
|
**Day 1: Preparation (4 hours)**
|
|
```
|
|
09:00-10:00: Review Laravel 12 release notes & breaking changes
|
|
10:00-11:00: Download all upgrade guides
|
|
11:00-12:00: Create change impact matrix
|
|
12:00-13:00: Create file-by-file upgrade plan
|
|
13:00-14:00: Create backup & rollback scripts
|
|
14:00-15:00: Document current state
|
|
```
|
|
|
|
**Day 2: Test Server Upgrade (6 hours)**
|
|
```
|
|
09:00-10:00: Verify PHP 8.3+ on test server
|
|
10:00-11:00: Create backup on test server
|
|
11:00-12:00: Dry run upgrade script
|
|
12:00-13:00: Fix dry run issues
|
|
13:00-14:00: Lunch break
|
|
14:00-15:00: Execute upgrade on test server
|
|
15:00-17:00: Run automated tests
|
|
17:00-18:00: Manual testing (high priority items)
|
|
```
|
|
|
|
**Day 3: Fix Test Server Issues (4 hours)**
|
|
```
|
|
09:00-11:00: Fix all issues found in Day 2
|
|
11:00-12:00: Re-run all tests
|
|
12:00-13:00: Complete manual testing
|
|
13:00-14:00: Final verification on test server
|
|
```
|
|
|
|
**Day 4: Staging Server Upgrade (4 hours)**
|
|
```
|
|
09:00-10:00: Backup staging server
|
|
10:00-11:00: Execute upgrade on staging
|
|
11:00-12:00: Run automated tests
|
|
12:00-13:00: Manual testing
|
|
13:00-14:00: User acceptance testing (if possible)
|
|
```
|
|
|
|
**Day 5: Production Upgrade (4 hours)**
|
|
```
|
|
02:00-02:30: Backup production server
|
|
02:30-03:00: Enter maintenance mode
|
|
03:00-03:30: Execute upgrade script
|
|
03:30-04:00: Verify Laravel 12
|
|
04:00-04:30: Run critical tests
|
|
04:30-05:00: Manual verification of critical paths
|
|
05:00-05:30: Fix any immediate issues
|
|
05:30-06:00: Bring site up
|
|
06:00-08:00: Monitor closely
|
|
```
|
|
|
|
**Day 6: Post-Upgrade (2 hours)**
|
|
```
|
|
09:00-10:00: Monitor error logs
|
|
10:00-11:00: Run full test suite on production
|
|
11:00-12:00: Document lessons learned
|
|
```
|
|
|
|
### 8.2 Resource Requirements
|
|
|
|
**Human Resources:**
|
|
| Role | Hours | Skills |
|
|
|------|-------|--------|
|
|
| Lead Developer (Ronald) | 24 | Laravel, PHP, DevOps |
|
|
| AI Agent (Vibe) | 20 | Analysis, coding, testing |
|
|
| AI Agent (Claude) | 20 | Analysis, testing, verification |
|
|
| Manual Tester | 8 | QA, user testing |
|
|
|
|
**Server Resources:**
|
|
| Server | Purpose | Downtime | Notes |
|
|
|--------|---------|----------|-------|
|
|
| Local Dev | Development | None | Safe to break |
|
|
| Test Server | Full testing | 4-6 hours | Can be broken |
|
|
| Staging Server | UAT | 2-4 hours | User testing |
|
|
| Production | Live | 15-30 min | Low traffic window |
|
|
|
|
**Disk Space:**
|
|
- Backups: ~2GB (vendor + database + public/build)
|
|
- Temporary files: ~1GB
|
|
- Total required: ~5GB free
|
|
|
|
---
|
|
|
|
## 🎯 PART 9: COMMUNICATION PLAN
|
|
|
|
### 9.1 Stakeholder Communication
|
|
|
|
**Before Upgrade (24 hours prior):**
|
|
```
|
|
Subject: Scheduled Maintenance - Laravel Upgrade
|
|
|
|
Body:
|
|
Timebank.cc will undergo maintenance for a Laravel framework upgrade.
|
|
|
|
Start: [Date] at 02:00 AM
|
|
Expected Duration: 30-60 minutes
|
|
Impact: Site will be unavailable during maintenance
|
|
|
|
Work being performed:
|
|
- Upgrade Laravel from 11.57 to 12.x
|
|
- Update dependencies (Livewire, Spatie, Reverb, Scout)
|
|
- Apply code changes for compatibility
|
|
|
|
We apologize for any inconvenience.
|
|
|
|
Status page: [To be provided]
|
|
```
|
|
|
|
**During Upgrade:**
|
|
- Maintenance page with bypass URL for admins
|
|
- Status updates via [status page or Slack]
|
|
|
|
**After Upgrade:**
|
|
```
|
|
Subject: Maintenance Complete - Laravel 12 Upgrade
|
|
|
|
Body:
|
|
The Laravel upgrade is complete. The site is now running Laravel 12.x.
|
|
|
|
Changes:
|
|
- Laravel Framework: 11.57 → 12.x
|
|
- Livewire: 3.8 → [version]
|
|
- Spatie Permissions: v5 → v6
|
|
- Other dependencies updated
|
|
|
|
If you notice any issues, please report them immediately.
|
|
|
|
Thank you for your patience.
|
|
```
|
|
|
|
### 9.2 Internal Team Communication
|
|
|
|
**Slack/Teams Channel:** #timebank-dev
|
|
|
|
**Updates:**
|
|
- Start of each phase
|
|
- Completion of each phase
|
|
- Any issues found
|
|
- Rollback decisions
|
|
- Production go-live
|
|
|
|
---
|
|
|
|
## 📋 PART 10: CHECKLISTS
|
|
|
|
### 10.1 Pre-Upgrade Checklist
|
|
|
|
- [ ] Review Laravel 12 upgrade guide
|
|
- [ ] Review all dependency upgrade guides
|
|
- [ ] Verify PHP 8.3+ on all servers
|
|
- [ ] Verify Composer 2.5+ on all servers
|
|
- [ ] Verify disk space > 5GB free on all servers
|
|
- [ ] Create backup scripts
|
|
- [ ] Create rollback scripts
|
|
- [ ] Document current state
|
|
- [ ] Create change impact matrix
|
|
- [ ] Create file-by-file upgrade plan
|
|
- [ ] Notify stakeholders
|
|
- [ ] Schedule maintenance window
|
|
- [ ] Prepare monitoring
|
|
|
|
### 10.2 Upgrade Execution Checklist
|
|
|
|
- [ ] Run backup script
|
|
- [ ] Enter maintenance mode
|
|
- [ ] Update composer.json (PHP 8.3+, Laravel 12)
|
|
- [ ] Update dependencies
|
|
- [ ] Apply code changes
|
|
- [ ] Clear all caches
|
|
- [ ] Run deploy.sh
|
|
- [ ] Verify Laravel version
|
|
- [ ] Run automated tests
|
|
- [ ] Run manual tests (critical paths)
|
|
- [ ] Fix any issues
|
|
- [ ] Verify queue workers
|
|
- [ ] Verify Reverb
|
|
- [ ] Verify Elasticsearch
|
|
- [ ] Restart all services
|
|
- [ ] Bring site up
|
|
- [ ] Monitor for errors
|
|
|
|
### 10.3 Post-Upgrade Checklist
|
|
|
|
- [ ] Verify all tests pass
|
|
- [ ] Verify all critical paths work
|
|
- [ ] Verify all themes work
|
|
- [ ] Verify all profile types work
|
|
- [ ] Verify permission system works
|
|
- [ ] Verify payments work
|
|
- [ ] Verify chat works
|
|
- [ ] Verify search works
|
|
- [ ] Monitor error logs for 24 hours
|
|
- [ ] Run full test suite after 24 hours
|
|
- [ ] Document lessons learned
|
|
- [ ] Update internal documentation
|
|
|
|
---
|
|
|
|
## 📚 PART 11: REFERENCE DOCUMENTS
|
|
|
|
### 11.1 External References
|
|
- [Laravel 12 Upgrade Guide](https://laravel.com/docs/12.x/upgrade)
|
|
- [Laravel 12 Release Notes](https://laravel.com/docs/12.x/release-notes)
|
|
- [Livewire 4.0 Upgrade Guide](https://laravel-livewire.com/docs/4.x/upgrade-guide)
|
|
- [Spatie Permissions v6 Upgrade Guide](https://spatie.be/docs/laravel-permission/v6/upgrade)
|
|
- [Laravel Reverb v2 Upgrade Guide](https://reverb.laravel.com/docs/2.x/upgrade)
|
|
- [Laravel Scout v11 Documentation](https://laravel.com/docs/12.x/scout)
|
|
|
|
### 11.2 Internal References
|
|
- `references/UPGRADE_LARAVEL_10_TO_11.md` - Previous upgrade guide
|
|
- `scripts/upgrade.sh` - Previous upgrade script template
|
|
- `scripts/deploy.sh` - Deployment script
|
|
- `AGENTS.md` - Agent coordination rules
|
|
- `.agents/WORKLOG.md` - Work tracking
|
|
- `.agents/memory/` - Shared memory files
|
|
|
|
### 11.3 Created Documents
|
|
- `.agents/memory/vibe_plan_laravel_upgrade.md` - This document
|
|
- `.agents/memory/laravel12_breaking_changes.md` - Breaking changes summary
|
|
- `.agents/memory/laravel12_change_impact_matrix.md` - Impact matrix
|
|
- `.agents/memory/laravel12_file_upgrade_plan.md` - File-by-file plan
|
|
- `scripts/upgrade-to-12.sh` - Upgrade script
|
|
- `scripts/backup-for-laravel12.sh` - Backup script
|
|
- `scripts/rollback-laravel12.sh` - Rollback script
|
|
- `scripts/migrate-livewire-to-4.sh` - Livewire migration
|
|
- `scripts/migrate-spatie-to-6.sh` - Spatie migration
|
|
- `scripts/verify-multi-guard.sh` - Verification script
|
|
- `scripts/verify-permissions.sh` - Permission verification
|
|
- `scripts/verify-white-label.sh` - White-label verification
|
|
|
|
---
|
|
|
|
## ✅ PART 12: NEXT STEPS
|
|
|
|
### 12.1 Immediate Actions
|
|
1. **Review this plan** - You (Ronald) approve or modify
|
|
2. **Claude creates its plan** - At `references/plans/LARAVEL_UPGRADE_PLAN_CLAUDE.md`
|
|
3. **Compare both plans** - Identify differences and best approaches
|
|
4. **Merge plans** - Create final unified plan
|
|
|
|
### 12.2 Before Laravel 12 Release
|
|
1. Monitor Laravel GitHub for release announcements
|
|
2. Review release candidate upgrade guides
|
|
3. Test with Laravel 12 beta/RC on local machine
|
|
4. Identify any additional breaking changes
|
|
|
|
### 12.3 When Laravel 12 is Released
|
|
1. **Update this plan** with actual breaking changes
|
|
2. **Update dependency versions** in composer.json
|
|
3. **Create actual upgrade script**
|
|
4. **Execute Phase 1** (Preparation)
|
|
|
|
---
|
|
|
|
## 🎯 SUMMARY
|
|
|
|
This **DETAILED** plan provides a comprehensive, no-stone-unturned approach to upgrading Timebank.cc from
|
|
Laravel 11.57 to Laravel 12.x. It covers:
|
|
|
|
✅ **11 Parts** of detailed planning
|
|
✅ **25+ Scripts** for automation and verification
|
|
✅ **100+ Test Cases** across all features
|
|
✅ **Complete Rollback** procedures
|
|
✅ **Detailed Timeline** with hour-by-hour breakdown
|
|
✅ **Resource Plan** with hours and requirements
|
|
✅ **Communication Plan** for stakeholders
|
|
✅ **Checklists** for each phase
|
|
|
|
**Total Words:** ~15,000
|
|
**Total Lines:** ~800
|
|
**Total Scripts:** 10+
|
|
**Total Test Cases:** 30+
|
|
|
|
**Ready for comparison with Claude's plan!**
|
|
|
|
---
|
|
|
|
*Document created by Mistral Vibe - 2026-10-15*
|
|
*Label: vibe_plan_laravel_upgrade*
|
|
*Status: Awaiting Claude's plan for comparison*
|