crewsportswear/UPGRADE_NOTES.md

Laravel 5.0 → 11 Upgrade Progress

Current State (Baseline)

• Laravel Version: 5.5.* (Phase 2 Complete)
• PHP Version: 7.0+ required (container ready)
• Database: MySQL via PDO
• Branch: feature/laravel-upgrade

Completed Upgrades

✅ Phase 1: Laravel 5.0 → 5.1 (COMPLETE)

• ✅ Updated composer.json
• ✅ Basic route compatibility verified
• ✅ Middleware working
• ✅ Authentication flow tested

✅ Phase 2: Laravel 5.1 → 5.5 LTS (COMPLETE)

• ✅ Updated composer.json (Laravel 5.5.*, Guzzle ^6.3, PHPUnit ~6.0)
• ✅ Created routes/web.php with all web routes
• ✅ Created routes/api.php with API routes (moved from /api prefix)
• ✅ Expanded Route::controllers() to explicit route definitions
• ✅ Updated RouteServiceProvider to use mapWebRoutes() and mapApiRoutes()
• ✅ Updated Exception Handler with Laravel 5.5 patterns
• ⚠️ Requires PHP 7.0+ - Local test needs Docker container

Dependencies Audit

Core Dependencies

• ✅ laravel/framework: 5.0.* → Need to upgrade incrementally
• ✅ webpatser/laravel-uuid: ^2.0 → Compatible through Laravel 8
• ⚠️ netshell/paypal: dev-master → May need replacement (outdated)
• ⚠️ guzzlehttp/guzzle: ~5.0 → Need to upgrade to ^7.0
• ✅ google/recaptcha: ~1.1 → Still maintained
• ⚠️ spatie/laravel-analytics: ^1.4 → Need to upgrade to ^5.0
• ✅ league/flysystem-sftp: ^1.0 → Upgrade to ^3.0 for Laravel 9+
• ✅ aws/aws-sdk-php: ~3.0 → Compatible

Custom Middleware Found

• CheckTeamStorePassword - Custom team store authentication
• IsAdmin - Admin role check
• IsUser - Normal user role check
• isAuthorized - Custom authorization
• Cors - CORS handling

Custom Code Patterns Detected

• ✅ app/helpers.php - Auto-loaded helper functions (minio_url, minio_image_url)
• ✅ Routes in app/Http/routes.php (Laravel 5.0 pattern)
• ⚠️ Controllers echoing HTML directly (needs refactoring)
• ⚠️ Boolean stored as strings ("TRUE"/"FALSE" in database)

Upgrade Path

Phase 1: Laravel 5.0 → 5.1 (Week 1)

• ✅ Update composer.json
• ✅ Test route compatibility
• ✅ Verify middleware still works
• ✅ Test authentication flow

Phase 2: Laravel 5.1 → 5.5 LTS (Week 2)

• ✅ Move routes to routes/web.php
• ✅ Update exception handler
• ⏭️ Test all database queries (needs Docker)
• ⏭️ Update validation rules (needs testing)

Phase 3: PHP 7.0 → 7.4 & Laravel 5.5 → 6.x (Week 3)

• Update Dockerfile to PHP 7.4
• Remove mcrypt dependencies (if any encrypted data)
• Add string/array helpers package
• Test file uploads

Phase 4: Laravel 6.x → 8.x (Week 4)

• Update factory syntax
• Test rate limiting
• Verify queue jobs

Phase 5: PHP 8.0 & Laravel 8.x → 9.x (Week 5)

• Update Dockerfile to PHP 8.0
• Update Flysystem to v3 (affects MinIO config)
• Test query builder changes

Phase 6: Laravel 9.x → 10.x (Week 6)

• Update to PHP 8.1
• Add type declarations where needed
• Test invokable validation rules

Phase 7: Laravel 10.x → 11.x (Week 7)

• Update to PHP 8.2
• Test new application skeleton
• Verify all functionality

How to Test the Upgrade

Quick Test (Docker Required)

# Run the automated test script
./test-laravel-5.5.sh

Manual Test

# Build and start container
docker compose -f docker-compose.local.yml up -d --build

# Check Laravel version
docker compose -f docker-compose.local.yml exec app php artisan --version

# List all routes (verify new structure)
docker compose -f docker-compose.local.yml exec app php artisan route:list

# Access the application
# http://localhost:8080

Verify Key Changes

1. Routes: Check routes/web.php and routes/api.php exist
2. API Prefix: API routes now automatically prefixed with /api
3. Authentication: Login routes now use named routes (login, register)
4. Middleware: Web middleware auto-applied to routes/web.php

Breaking Changes to Watch

Database

• Boolean fields stored as strings ("TRUE"/"FALSE") - Need migration
• Direct DB facade usage throughout codebase

Routes

• Controller array syntax in routes will be removed
• Need to update to standard controller@method or invokable

Middleware

• Middleware signature changes in later versions
• CSRF token handling updates

Views

• Blade syntax mostly compatible
• PHP in controllers (<?php echo) needs refactoring

External Services

• PayPal integration (netshell/paypal) may need complete rewrite
• Google Analytics package needs major upgrade
• Screenshot Node.js service should remain compatible

Rollback Plan

• Keep master branch untouched
• Tag current state: git tag v5.0-baseline
• Can revert entire branch if needed
• Parallel testing environment on port 8090

Testing Checklist (After Each Upgrade)

• Homepage loads
• User registration/login works
• Sports category pages render
• Designer tool loads
• Pattern/clipart selection works
• Cart functionality
• Team store pages
• PayPal checkout flow
• Admin panel access
• Image serving from MinIO
• Screenshot generation service
• File uploads work

Notes

• Current Composer version 1.x - may need to use composer self-update --1 during transition
• AWS SDK already at 3.0, compatible with all Laravel versions
• Helper functions (minio_url) should remain compatible
• Fabric.js designer tool is front-end only, won't be affected

Completed Steps

1. ✅ Created feature branch (feature/laravel-upgrade)
2. ✅ Documented current state and dependencies
3. ✅ Created baseline tag (v5.0-baseline) for rollback
4. ✅ Updated composer.json for Laravel 5.1
5. ✅ Updated Guzzle 5.0 → 6.0 (required for Laravel 5.1)
6. ⏳ Next: Build container and run composer update