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

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

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

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

Integration with Other Skills