diff --git a/docs/SYMFONY_7.4_UPGRADE_PLAN.md b/docs/SYMFONY_7.4_UPGRADE_PLAN.md new file mode 100644 index 0000000..d495621 --- /dev/null +++ b/docs/SYMFONY_7.4_UPGRADE_PLAN.md @@ -0,0 +1,505 @@ +# Symfony 7.4 Upgrade Plan + +**Project:** MyEP Next Booking +**Current Version:** Symfony 6.4.27 +**Target Version:** Symfony 7.4 (LTS) +**Date:** 2025-12-06 +**Status:** Ready for Upgrade + +--- + +## Executive Summary + +**Estimated Effort: LOW** +**Risk Level: LOW** +**Status: READY FOR UPGRADE** + +The MyEP Next Booking application is well-positioned for a Symfony 7.4 upgrade. The codebase follows modern Symfony best practices, uses PHP 8 features extensively, and avoids most deprecated patterns. + +**Key Facts:** +- Symfony 7.4 was released on November 27, 2025 +- Requires PHP 8.2.0+ (current: PHP 8.2.29) +- LTS version with bug fixes until November 2028, security fixes until November 2029 +- Symfony 8.0 = Symfony 7.4 minus deprecations (same features, PHP 8.4 required) + +**Pre-Upgrade Status:** +- PHP version: 8.2.29 (compatible) +- OAuth2 Server Bundle: 1.0.0 (compatible) +- Stimulus Bundle: 2.31.0 (compatible) +- KnpMenuBundle: Removed (no longer in use) +- Doctrine ORM: 3.5.8 (compatible) +- All 281 tests passing (1 unrelated test failure to investigate) +- 18 deprecation warnings to resolve (Email validator loose mode) + +--- + +## Previous Plan Status + +The previous upgrade plan (dated 2025-10-24) was written for Symfony 7.3. Several items have changed: + +### Completed Items +| Item | Previous Status | Current Status | +|------|----------------|----------------| +| OAuth2 Server Bundle | ^1.0 | **1.0.0 installed** | +| Stimulus Bundle | ^2.30 | **2.31.0 installed** | +| PHP 8.2 deprecations (ParticipantDto::$touched) | Planned | **Completed** | +| Doctrine config (controller_resolver) | Planned | **Completed** | +| SecurityController null safety | Planned | **Needs verification** | + +### Items No Longer Relevant +| Item | Reason | +|------|--------| +| KnpMenuBundle upgrade | **Bundle removed from project** | + +### New Items Discovered +| Item | Priority | Status | +|------|----------|--------| +| Email validator "loose" mode deprecation | MEDIUM | **Needs fix** | +| Failing test in BookingDataProcessorTest | LOW | **Unrelated to upgrade** | + +--- + +## Current State Analysis + +### PHP Version Compatibility + +- **Current Runtime:** PHP 8.2.29 +- **Composer Platform:** PHP 8.2.28 +- **Symfony 7.4 Required:** PHP 8.2.0+ +- **Status:** Compatible + +### Installed Dependencies + +#### Core Symfony Packages (6.4.x) +All 32 Symfony packages currently at 6.4.x need version constraint updates to 7.4.* + +#### Third-Party Bundles - Compatible +| Package | Installed | Symfony 7.4 Compatible | +|---------|-----------|------------------------| +| `doctrine/orm` | 3.5.8 | Yes | +| `doctrine/doctrine-bundle` | 2.18.1 | Yes | +| `doctrine/doctrine-migrations-bundle` | 3.7.0 | Yes | +| `league/oauth2-server-bundle` | 1.0.0 | Yes | +| `symfony/stimulus-bundle` | 2.31.0 | Yes | +| `symfony/webpack-encore-bundle` | 2.4.0 | Yes | +| `symfony/monolog-bundle` | 3.11.0 | Yes | +| `zenstruck/schedule-bundle` | ^1.8 | Verify during upgrade | + +### Code Quality Assessment + +The codebase implements modern Symfony/PHP patterns: +- All controllers use PHP 8 attributes (`#[Route]`) +- Constructor property promotion used throughout +- Strict types enforced on all files +- Typed properties and return type declarations +- Entities use PHP 8 attributes for ORM mapping +- Modern security system (AbstractLoginFormAuthenticator) +- No deprecated annotation usage + +--- + +## Pre-Upgrade Fixes Required + +### 1. Email Validator "loose" Mode Deprecation (MEDIUM Priority) + +**Issue:** The default mode for `#[Assert\Email]` is "loose", which is deprecated in Symfony 6.2+ and removed in Symfony 7.0. + +**Current State:** Most Email constraints already have `mode: 'strict'`, but the framework default is still being triggered somewhere during validation. + +**Files to verify:** +- `src/Form/Model/ParticipantDto.php` - Has `mode: 'strict'` ✓ +- `src/Form/Model/RegistrationDto.php` - Has `mode: 'strict'` ✓ +- `src/BusProNet/Model/Communication.php` - Has `mode: 'strict'` ✓ +- `src/Controller/ResetPasswordController.php` - Has `mode: 'strict'` ✓ + +**Action:** Configure framework default email validation mode in `config/packages/validator.yaml`: + +```yaml +framework: + validation: + email_validation_mode: html5 +``` + +This sets the global default to `html5` (recommended for Symfony 7+), eliminating deprecation warnings. + +### 2. Test Failure Investigation (LOW Priority) + +**File:** `tests/BusProNet/DataProcessor/BookingDataProcessorTest.php:171` +**Issue:** Expected 'Original', got 'Updated' + +This appears to be a test that's failing due to recent code changes unrelated to the Symfony upgrade. Should be investigated separately but does not block the upgrade. + +--- + +## Required Changes + +### 1. Update Composer Version Constraints + +**File:** `composer.json` + +#### Symfony Core Packages +Update all packages from `6.4.*` to `7.4.*`: + +```json +{ + "require": { + "symfony/asset": "7.4.*", + "symfony/console": "7.4.*", + "symfony/doctrine-messenger": "7.4.*", + "symfony/dom-crawler": "7.4.*", + "symfony/dotenv": "7.4.*", + "symfony/expression-language": "7.4.*", + "symfony/form": "7.4.*", + "symfony/framework-bundle": "7.4.*", + "symfony/html-sanitizer": "7.4.*", + "symfony/http-client": "7.4.*", + "symfony/intl": "7.4.*", + "symfony/mailer": "7.4.*", + "symfony/mime": "7.4.*", + "symfony/notifier": "7.4.*", + "symfony/process": "7.4.*", + "symfony/property-access": "7.4.*", + "symfony/property-info": "7.4.*", + "symfony/runtime": "7.4.*", + "symfony/security-bundle": "7.4.*", + "symfony/serializer": "7.4.*", + "symfony/string": "7.4.*", + "symfony/translation": "7.4.*", + "symfony/twig-bundle": "7.4.*", + "symfony/uid": "7.4.*", + "symfony/validator": "7.4.*", + "symfony/web-link": "7.4.*", + "symfony/yaml": "7.4.*" + } +} +``` + +#### Development Packages + +```json +{ + "require-dev": { + "symfony/browser-kit": "7.4.*", + "symfony/css-selector": "7.4.*", + "symfony/debug-bundle": "7.4.*", + "symfony/stopwatch": "7.4.*", + "symfony/web-profiler-bundle": "7.4.*" + } +} +``` + +### 2. Update Symfony Flex Configuration + +**File:** `composer.json` + +```json +{ + "extra": { + "symfony": { + "allow-contrib": true, + "require": "7.4.*", + "docker": true + } + } +} +``` + +### 3. Configure Email Validation Mode + +**File:** `config/packages/validator.yaml` + +```yaml +framework: + validation: + email_validation_mode: html5 +``` + +--- + +## Potential Breaking Changes + +### 1. Symfony Core Changes (Symfony 7.0 → 7.4) + +Symfony 7.0 removed all deprecated features from 6.4. Our codebase is mostly compliant: + +- **Native Return Types:** Already implemented +- **Attribute-based Configuration:** Already implemented +- **Security System:** Modern authenticator pattern in use +- **Form System:** Modern approach in use +- **No Annotation Usage:** All using PHP 8 attributes + +### 2. Email Validation Mode + +**Breaking Change:** The default `mode` for `Email` constraint changes from `loose` to `html5` in Symfony 7.0. + +**Status:** Already using `mode: 'strict'` in most places. Setting global default will ensure consistency. + +### 3. Deprecation Cleanup + +Deprecations accumulated in Symfony 7.1-7.4 will need review: +- Check Symfony Profiler after upgrade for any new deprecation warnings +- Review [UPGRADE-7.0.md](https://github.com/symfony/symfony/blob/7.0/UPGRADE-7.0.md) +- Review [UPGRADE-7.4.md](https://github.com/symfony/symfony/blob/7.4/UPGRADE-7.4.md) + +--- + +## Upgrade Procedure + +### Phase 1: Pre-Upgrade Fixes (30 minutes) + +1. **Configure Email Validation Mode** + ```bash + # Edit config/packages/validator.yaml + ``` + +2. **Clear Caches** + ```bash + ddev exec bin/console cache:clear + ddev exec "php -r 'opcache_reset();'" + ``` + +3. **Run Tests** + ```bash + ddev exec ./vendor/bin/phpunit + ``` + Verify deprecation warnings are resolved. + +### Phase 2: Preparation (15 minutes) + +1. **Create Feature Branch** + ```bash + git checkout -b feature/symfony-7.4-upgrade + ``` + +2. **Backup Current State** + ```bash + git tag before-symfony-7.4-upgrade + ``` + +### Phase 3: Dependency Updates (30 minutes - 1 hour) + +1. **Update composer.json** + - Update all Symfony package constraints to `7.4.*` + - Update `extra.symfony.require` to `"7.4.*"` + +2. **Run Composer Update** + ```bash + ddev composer update + ``` + +3. **Review Recipe Updates** + ```bash + ddev composer recipes + ``` + Review any recipe updates from Symfony Flex and apply as needed. + +4. **Clear All Caches** + ```bash + ddev exec bin/console cache:clear + ddev exec bin/console cache:warmup + ddev exec "php -r 'opcache_reset();'" + ``` + +### Phase 4: Testing & Validation (1-2 hours) + +1. **Run PHPUnit Test Suite** + ```bash + ddev exec ./vendor/bin/phpunit + ``` + Check for: + - Test failures + - Deprecation warnings + - Fatal errors + +2. **Run PHP-CS-Fixer** + ```bash + /opt/homebrew/bin/php-cs-fixer fix --dry-run --diff + ``` + +3. **Manual Testing - Critical Paths** + - [ ] User authentication (BPN API login) + - [ ] OAuth2 token generation (`/token` endpoint) + - [ ] OAuth2 authorization flow (`/authorize` endpoint) + - [ ] API endpoints (all `/api/*` routes) + - [ ] Booking creation flow (Steps 1-4) + - [ ] Participant form rendering and submission + - [ ] Dynamic field updates (HTMX) + - [ ] Real-time pricing calculations + - [ ] Insurance selection and filtering + - [ ] Transportation service selection + - [ ] Payment method selection + - [ ] Final booking submission to BPN API + - [ ] Booking edit functionality + - [ ] PDF/XML download functionality + - [ ] User registration + - [ ] Password reset + - [ ] Personal data management + +4. **Check Symfony Profiler** + - Review deprecation warnings (should be minimal) + - Check performance metrics + - Verify no errors in logs + +5. **Test Frontend Assets** + ```bash + npm run build + ``` + - Verify Stimulus controllers load correctly + - Test HTMX interactions + - Verify Toastify notifications + - Check TailwindCSS compilation + +### Phase 5: Bug Fixes (0-2 hours) + +Address any issues discovered during testing: + +1. **Review Error Logs** + ```bash + ddev logs + ``` + +2. **Fix Any Remaining Deprecations** + - Use Symfony Profiler to identify deprecations + - Update code to use modern alternatives + +### Phase 6: Deployment (1 hour) + +1. **Deploy to Staging** + ```bash + ddev exec vendor/bin/dep deploy staging + ``` + +2. **Staging Validation** + - Full regression testing + - Performance testing + +3. **Production Deployment** + - Schedule maintenance window + - Deploy during low-traffic period + - Monitor error logs closely + +--- + +## Rollback Plan + +### Immediate Rollback + +If critical issues are discovered: + +1. **Git Revert** + ```bash + git checkout master + git reset --hard before-symfony-7.4-upgrade + ``` + +2. **Restore Dependencies** + ```bash + ddev composer install + ``` + +3. **Clear Caches** + ```bash + ddev exec bin/console cache:clear + ``` + +### Production Rollback + +If issues occur in production: + +```bash +ddev exec vendor/bin/dep rollback production +``` + +--- + +## Testing Checklist + +### Unit Tests +- [ ] All PHPUnit tests pass +- [ ] No new deprecation warnings +- [ ] Code coverage maintained + +### Integration Tests +- [ ] BusProNet API integration +- [ ] XML parsing and data processing +- [ ] Booking price calculations +- [ ] Insurance assignment logic +- [ ] Field handler system + +### Functional Tests +- [ ] User authentication flow +- [ ] OAuth2 token generation +- [ ] API endpoints respond correctly +- [ ] Booking creation (all steps) +- [ ] Form validation +- [ ] HTMX partial updates +- [ ] Dynamic field state changes +- [ ] Real-time pricing updates +- [ ] Toast notifications + +### Browser Testing +- [ ] Chrome (latest) +- [ ] Firefox (latest) +- [ ] Safari (latest) +- [ ] Mobile browsers + +--- + +## Timeline Estimate + +| Phase | Estimated Time | Notes | +|-------|---------------|-------| +| **Phase 1:** Pre-Upgrade Fixes | 30 min | Email validation mode config | +| **Phase 2:** Preparation | 15 min | Branch creation | +| **Phase 3:** Dependency Updates | 30 min - 1 hour | composer.json updates, composer update | +| **Phase 4:** Testing & Validation | 1-2 hours | Automated + manual testing | +| **Phase 5:** Bug Fixes | 0-2 hours | Address any issues | +| **Phase 6:** Deployment | 1 hour | Staging deployment | +| **Total** | **3-6 hours** | Average: **4 hours** | + +--- + +## Future Considerations: Symfony 8.0 + +Symfony 8.0 was released alongside 7.4 (November 2025) with identical features but: +- Requires PHP 8.4 +- No deprecation layers (all deprecated code removed) +- Shorter support window (8 months) + +**Recommendation:** Stay on Symfony 7.4 LTS for stability. Plan PHP 8.4 upgrade separately, then consider Symfony 8.x path. + +--- + +## Success Criteria + +- [ ] All PHPUnit tests pass +- [ ] No deprecation warnings in Symfony Profiler +- [ ] All critical user flows functional +- [ ] OAuth2 authentication working +- [ ] BPN API integration operational +- [ ] Booking creation flow complete +- [ ] Frontend assets compile and load +- [ ] Performance metrics comparable or better +- [ ] No errors in production logs after 24 hours + +--- + +## Additional Resources + +### Official Symfony Documentation +- [Upgrade Major Version Guide](https://symfony.com/doc/current/setup/upgrade_major.html) +- [UPGRADE-7.0.md](https://github.com/symfony/symfony/blob/7.0/UPGRADE-7.0.md) +- [UPGRADE-7.4.md](https://github.com/symfony/symfony/blob/7.4/UPGRADE-7.4.md) +- [Symfony 7.4 Release Notes](https://symfony.com/releases/7.4) +- [Preparing for Symfony 7.4 and 8.0](https://symfony.com/blog/preparing-for-symfony-7-4-and-symfony-8-0) + +### Bundle-Specific Documentation +- [OAuth2 Server Bundle](https://github.com/thephpleague/oauth2-server-bundle) +- [Doctrine ORM 3.x Documentation](https://www.doctrine-project.org/projects/orm.html) + +--- + +**Document Version:** 4.0 +**Previous Version:** 3.0 (Symfony 7.3 plan, dated 2025-10-24) +**Last Updated:** 2025-12-06 +**Status:** Ready for Symfony 7.4 Upgrade