506 lines
14 KiB
Markdown
506 lines
14 KiB
Markdown
# 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
|