myep/docs/SYMFONY_7.4_UPGRADE_PLAN.md

# Symfony 7.4 Upgrade Plan

**Project:** MyEP Next Booking
**Current Version:** Symfony 6.4.31
**Target Version:** Symfony 7.4 (LTS)
**Date:** 2026-01-05
**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. All pre-upgrade fixes have been completed.

**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.1.0 (compatible)
- Stimulus Bundle: 2.32.0 (compatible)
- KnpMenuBundle: Removed (no longer in use)
- Doctrine ORM: 3.6.0 (compatible)
- All 312 tests passing
- Email validation mode: Configured (html5)
- 18 test-only deprecation warnings (cosmetic, do not affect runtime)

---

## Previous Plan Status

The previous upgrade plan (dated 2025-12-06) has been updated. All pre-upgrade tasks are now complete.

### Completed Items
| Item | Previous Status | Current Status |
|------|----------------|----------------|
| OAuth2 Server Bundle | 1.0.0 | **1.1.0 installed** |
| Stimulus Bundle | 2.31.0 | **2.32.0 installed** |
| PHP 8.2 deprecations (ParticipantDto::$touched) | Planned | **Completed** |
| Doctrine config (controller_resolver) | Planned | **Completed** |
| SecurityController null safety | Needs verification | **Completed** (uses `?->` and `??`) |
| Email validator "loose" mode deprecation | Needs fix | **Completed** (validator.yaml configured) |
| Failing test in BookingDataProcessorTest | Unrelated to upgrade | **Resolved** (test now passes) |

### Items No Longer Relevant
| Item | Reason |
|------|--------|
| KnpMenuBundle upgrade | **Bundle removed from project** |

---

## 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 33 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.6.0 | Yes |
| `doctrine/doctrine-bundle` | 2.18.1 | Yes |
| `doctrine/doctrine-migrations-bundle` | 3.7.0 | Yes |
| `league/oauth2-server-bundle` | 1.1.0 | Yes |
| `symfony/stimulus-bundle` | 2.32.0 | Yes |
| `symfony/webpack-encore-bundle` | 2.4.0 | Yes |
| `symfony/monolog-bundle` | 3.11.0 | Yes |
| `zenstruck/schedule-bundle` | 1.9.0 | Yes |

### 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 - COMPLETED

### 1. Email Validator "loose" Mode Deprecation - DONE

**Issue:** The default mode for `#[Assert\Email]` is "loose", which is deprecated in Symfony 6.2+ and removed in Symfony 7.0.

**Resolution:** Framework default configured in `config/packages/validator.yaml`:

```yaml
framework:
    validation:
        email_validation_mode: html5
```

All Email constraints in the codebase also explicitly use `mode: 'strict'`:
- `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'`

### 2. Test Deprecation Warnings - COSMETIC ONLY

**Issue:** 18 deprecation warnings appear during test runs.

**Cause:** `ParticipantEditDtoTest` creates a standalone validator using `Validation::createValidatorBuilder()` which bypasses the framework's `validator.yaml` configuration.

**Impact:** These warnings are cosmetic and do not affect:
- Runtime behavior (all Email constraints use explicit `mode: 'strict'`)
- Symfony 7.4 compatibility (no code changes needed)
- Test results (all 312 tests pass)

**Note:** Warnings can be silenced with `SYMFONY_DEPRECATIONS_HELPER=disabled` if desired.

---

## 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/lock": "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
    }
  }
}
```

---

## 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 fully 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 handled - all constraints use explicit `mode: 'strict'` and framework default is set to `html5`.

### 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: 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 2: 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 3: 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
   ddev php vendor/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 4: 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 5: 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 (312 tests)
- [ ] 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:** Preparation | 15 min | Branch creation |
| **Phase 2:** Dependency Updates | 30 min - 1 hour | composer.json updates, composer update |
| **Phase 3:** Testing & Validation | 1-2 hours | Automated + manual testing |
| **Phase 4:** Bug Fixes | 0-2 hours | Address any issues |
| **Phase 5:** Deployment | 1 hour | Staging deployment |
| **Total** | **2.5-6 hours** | Average: **3.5 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 (312 tests)
- [ ] 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:** 5.0
**Previous Version:** 4.0 (dated 2025-12-06)
**Last Updated:** 2026-01-05
**Status:** Ready for Symfony 7.4 Upgrade