krzysztofsurdy/symfony-upgrade

Symfony Framework Upgrade

Symfony's upgrade model is built on one core insight: a new major version is identical to the last minor version of the previous branch, minus deprecated code. Fix all deprecations first, then the major upgrade is trivial.

Core Principles

| Principle | Meaning | |---|---| | Changelog first | Before any upgrade, search the web for the actual UPGRADE-X.Y.md file or ask the user for the changelog - never rely on static knowledge alone | | Deprecation-first | Fix every deprecation on the current version before upgrading to the next major - Symfony 8.0 is 7.4 minus deprecations | | Incremental minor upgrades | Upgrade 6.2 -> 6.3 -> 6.4, never skip minors - each surfaces new deprecations | | Recipes keep config current | Run composer recipes:update after every upgrade to sync configuration files | | Test deprecation count | Use SYMFONY_DEPRECATIONS_HELPER to fail builds when direct deprecations appear | | Update bundles first | Third-party bundles are the most common blocker - update them before bumping Symfony |

---

Critical First Step: Read the Changelog

Before touching any code or running any command, you MUST obtain the actual changelog for the target version:

1. Search the web for Symfony UPGRADE-X.Y.md (e.g., Symfony UPGRADE-7.0.md github)
2. Or ask the user to provide the changelog / release notes
3. Read the UPGRADE file in the Symfony repository: https://github.com/symfony/symfony/blob/X.Y/UPGRADE-X.Y.md
4. Check the Symfony blog for the release announcement with highlighted changes

This is non-negotiable. Each version has unique changes that static skill knowledge cannot fully capture. The changelog tells you exactly what broke, what was deprecated, and what was removed.

---

Symfony Release Model

| Release Type | Cycle | Support | Example | |---|---|---|---| | Patch (X.Y.Z) | Monthly | Bug fixes only | 7.4.1 -> 7.4.2 | | Minor (X.Y) | Every 6 months (May + November) | May add deprecations, no BC breaks | 7.3 -> 7.4 | | Major (X.0) | Every 2 years (November, odd years) | Removes deprecated code, may have BC breaks | 7.x -> 8.0 | | LTS (X.4) | Always the X.4 release | 3 years bug fixes, 4 years security fixes | 6.4 LTS, 7.4 LTS |

Each major branch has exactly 5 minor versions: X.0, X.1, X.2, X.3, X.4 (LTS).

---

Minor Version Upgrade (e.g., 7.3 -> 7.4)

Step 1: Read the Changelog

Search the web for UPGRADE-7.4.md in the Symfony repository. Identify new deprecations and any changes that affect your code.

Step 2: Update composer.json

With Symfony Flex (recommended):

{
    "extra": {
        "symfony": {
            "require": "7.4.*"
        }
    }
}

Without Flex, update each symfony/* constraint manually.

Step 3: Run Composer Update

composer update "symfony/*"

If dependency conflicts arise:

composer update "symfony/*" --with-all-dependencies

Step 4: Update Recipes

composer recipes:update

Step 5: Run Tests

vendor/bin/phpunit

---

Major Version Upgrade (e.g., 6.4 -> 7.0)

Phase 1: Read the Changelog

Search the web for UPGRADE-7.0.md in the Symfony repository. This file lists every backward-compatibility break and every removed deprecation. Read it completely before starting.

Phase 2: Eliminate All Deprecations

This is the bulk of the work. Do this while still on the current major version.

A. Detect deprecations via tests:

composer require --dev symfony/phpunit-bridge

Configure strict deprecation handling in phpunit.xml.dist:

<php>
    <env name="SYMFONY_DEPRECATIONS_HELPER" value="max[direct]=0"/>
</php>

Run tests and fix every direct deprecation:

vendor/bin/phpunit

B. Detect deprecations in browser:

Visit the app in dev environment, check the Symfony Profiler's deprecation panel in the web debug toolbar.

C. Automate fixes with Rector:

composer require --dev rector/rector rector/rector-symfony

// rector.php
use Rector\Config\RectorConfig;
use Rector\Symfony\Set\SymfonySetList;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withSets([SymfonySetList::SYMFONY_70]);

vendor/bin/rector process --dry-run
vendor/bin/rector process

D. Handle indirect deprecations:

Indirect deprecations come from third-party bundles. Update them to versions that support the target Symfony version:

composer outdated
composer update vendor/bundle-name

Phase 3: Bump Symfony Version

With Flex:

{
    "extra": {
        "symfony": {
            "require": "7.0.*"
        }
    }
}

composer update "symfony/*" --with-all-dependencies
rm -rf var/cache/*

Note: packages like symfony/polyfill-*, symfony/ux-*, and some symfony/*-bundle follow their own versioning - do not force them to the new major.

Phase 4: Update Recipes

composer recipes              # list all, see which have updates
composer recipes:update       # interactive update, one at a time

The command generates a diff between your installed recipe version and the latest, applies it as a git patch. Resolve conflicts like normal git conflicts. Commit your work before running this.

Phase 5: Test Thoroughly

vendor/bin/phpunit
vendor/bin/phpstan analyse

Deploy to staging before production.

See Upgrade Workflow Reference for detailed deprecation handling, SYMFONY_DEPRECATIONS_HELPER options, and bundle compatibility strategies.

---

SYMFONY_DEPRECATIONS_HELPER Options

| Configuration | Effect | |---|---| | max[direct]=0 | Fail on any deprecation caused by your code | | max[indirect]=999 | Tolerate deprecations from vendor code during transition | | max[total]=0 | Fail on any deprecation from any source (strictest) | | disabled=1 | Disable deprecation tracking entirely (not recommended) | | generateBaseline=true&baselineFile=./tests/allowed.json | Snapshot current deprecations to a baseline file | | baselineFile=./tests/allowed.json | Ignore deprecations already in the baseline (ratchet approach) |

---

Handling Third-Party Bundles

Bundles are the most common upgrade blocker. Follow this order:

1. Check compatibility - look at each bundle's composer.json for Symfony version constraints
2. Update bundles first - composer update before bumping Symfony version
3. Check for forks - if a bundle is abandoned, look for maintained forks on Packagist
4. Wrap risky dependencies - use adapter pattern to isolate bundles that may not keep up

For bundle maintainers, use feature detection instead of version checks:

// Bad - version-based check
if (Kernel::VERSION_ID <= 60400) { ... }

// Good - feature-based check
if (!method_exists(OptionsResolver::class, 'setDefined')) { ... }

Support multiple versions with flexible constraints:

{
    "require": {
        "symfony/framework-bundle": "^6.4|^7.0"
    }
}

---

Quick Reference: Major Upgrade Checklist

• [ ] Search the web for UPGRADE-X.0.md and read it completely
• [ ] Upgrade to the last minor of current major (e.g., 6.4)
• [ ] Update all third-party bundles to latest versions
• [ ] Configure SYMFONY_DEPRECATIONS_HELPER with max[direct]=0
• [ ] Run test suite and fix all direct deprecations
• [ ] Run Rector with Symfony deprecation rules
• [ ] Verify zero direct deprecations in test output
• [ ] Update extra.symfony.require to new major version
• [ ] Run composer update "symfony/*" --with-all-dependencies
• [ ] Clear cache: rm -rf var/cache/*
• [ ] Run composer recipes:update until all recipes are current
• [ ] Run full test suite
• [ ] Run static analysis
• [ ] Deploy to staging and verify
• [ ] Deploy to production and monitor logs

---

Reference Files

| Reference | Contents | |---|---| | Upgrade Workflow | Detailed deprecation handling workflow, recipes:update deep dive, CI pipeline integration, and version-specific migration notes |

---

Integration with Other Skills

| Situation | Recommended Skill | |---|---| | Upgrading PHP version alongside Symfony | Use the php-upgrade playbook skill | | Updating Composer dependencies | Use the composer-dependencies playbook skill | | Working with Symfony components | Use the symfony-components skill in frameworks/symfony/ | | Modernizing PHP code patterns | Install php-modernization from dirnbauer/webconsulting-skills |