symfony-upgrade

Symfony 框架升级

Symfony 的升级模式基于一个事实：新主版本就是移除了已弃用代码的上一分支最后一个次版本。先修复所有弃用项，主版本升级就会轻松许多。

核心原则

原则	含义
先读变更日志	每次升级前，先阅读目标版本的 UPGRADE-X.Y.md 文件，以及所用 Symfony 软件包的 CHANGELOG.md。不要只依赖内置知识
优先处理弃用项	升级到下一个主版本前，先修复当前版本中的所有弃用项。Symfony 8.0 就是移除了弃用项的 7.4
逐步升级次版本	按 6.2 -> 6.3 -> 6.4 的顺序升级，不要跳过次版本，因为每个版本都会暴露新的弃用项
通过 Recipes 保持配置最新	每次升级后运行 composer recipes:update，同步配置文件
测试弃用项数量	使用 SYMFONY_DEPRECATIONS_HELPER，在出现直接弃用项时让构建失败
先更新 Bundles	第三方 Bundle 是最常见的阻碍因素——升级 Symfony 前先更新它们

---

第一步：阅读变更日志

修改任何代码或运行任何命令前，先了解目标版本有哪些变化：

1. 使用 docs-lookup skill 获取 Symfony 升级文档和目标版本的 UPGRADE-X.Y.md 文件（文件名中的版本号就是目标版本：UPGRADE-8.0.md 介绍 7.4 -> 8.0，UPGRADE-8.1.md 介绍 8.0 -> 8.1）
2. 如果没有该 skill，请从 Symfony 仓库中阅读：https://github.com/symfony/symfony/blob/X.Y/UPGRADE-X.Y.md
3. 检查已安装的软件包。 每个 Symfony 软件包都在自己的 vendor/symfony/<package>/CHANGELOG.md 中记录该软件包的弃用项和 BC 变更。UPGRADE-*.md 文件不在这些软件包中。只有当项目依赖完整的 symfony/symfony 软件包时，这些文件才会位于 vendor/symfony/symfony/ 中，因此 vendor/symfony/*/UPGRADE-*.md 通常匹配不到任何文件
4. 查看 Symfony 博客，了解重点介绍变化的版本发布公告
5. 或者请用户提供发行说明

不要跳过这一步。每个版本都有此 skill 无法完整涵盖的专属变化。UPGRADE 文件会准确列出哪些内容发生了破坏性变化、哪些内容已弃用，以及哪些内容已移除。

---

Symfony 发布模式

发布类型	周期	支持	示例
补丁版（X.Y.Z）	每月	仅修复错误	7.4.1 -> 7.4.2
次版本（X.Y）	每 6 个月（5 月和 11 月）	可能新增弃用项，不包含 BC 变更	7.3 -> 7.4
主版本（X.0）	每 2 年一次（奇数年的 11 月）	移除已弃用代码，可能包含 BC 变更	7.x -> 8.0
LTS（X.4）	始终为 X.4 版本	3 年错误修复支持，4 年安全修复支持	6.4 LTS、7.4 LTS

每个主版本分支恰好有 5 个次版本：X.0、X.1、X.2、X.3、X.4（LTS）。

最低 PHP 版本

Symfony	最低 PHP 版本
6.4 LTS	8.1.0
7.4 LTS	8.2.0
8.0	8.4.0
8.1	8.4.1

Symfony 8.0 和 8.1 都需要 PHP 8.4 或更高版本，因此从 7.4 升级到 8.x 也意味着升级 PHP。先在当前运行的 Symfony 版本上升级 PHP（参见 php-upgrade skill），然后再升级 Symfony。请查看 https://symfony.com/releases.json（min_php_requirements）或软件包 composer.json 中的 php 约束，以确定目标版本的准确要求。

---

次版本升级（例如 7.3 -> 7.4）

步骤 1：阅读变更日志

阅读 UPGRADE-7.4.md（参见“第一步：阅读变更日志”）。记下新增的弃用项，以及会影响代码的任何变化。

步骤 2：更新 composer.json

使用 Symfony Flex（推荐）：

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

不使用 Flex 时，手动更新每个 symfony/* 约束。

步骤 3：运行 composer update

composer update "symfony/*"

如果出现依赖冲突：

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

步骤 4：更新 Recipes

composer recipes:update

步骤 5：运行测试

vendor/bin/phpunit

---

主版本升级（例如 6.4 -> 7.0）

阶段 1：阅读变更日志

阅读 UPGRADE-7.0.md（参见“第一步：阅读变更日志”）。其中列出了所有不向后兼容的变更和所有已移除的弃用项。开始前请通读全文。

阶段 2：消除所有弃用项

这是大部分工作。请在当前主版本下完成。

A. 通过测试检测弃用项：

composer require --dev symfony/phpunit-bridge

在 phpunit.xml.dist 中启用严格的弃用处理：

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

运行测试并修复每一处直接弃用：

vendor/bin/phpunit

B. 在浏览器中检测弃用项：

在开发环境中打开应用，并检查 Web 调试工具栏中 Symfony Profiler 的弃用面板。

C. 使用 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. 处理间接弃用：

间接弃用来自第三方 bundle。请将这些 bundle 更新到支持目标 Symfony 版本的版本：

composer outdated
composer update vendor/bundle-name

阶段 3：升级 Symfony 版本

使用 Flex：

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

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

Symfony/polyfill-*、symfony/ux-* 等包，以及部分 symfony/*-bundle 包，都遵循自己的版本策略。不要强制将它们升级到新的主版本。

阶段 4：更新 recipes

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

该命令会对比已安装的 recipe 版本与最新版本，生成差异并将其作为 git 补丁应用。请像解决任何 git 冲突一样解决冲突。运行前请先提交工作。

阶段 5：测试

vendor/bin/phpunit
vendor/bin/phpstan analyse

先部署到预发布环境，再部署到生产环境。

弃用处理、SYMFONY_DEPRECATIONS_HELPER 选项和 bundle 兼容性策略，请参阅 升级工作流参考。

---

SYMFONY_DEPRECATIONS_HELPER 选项

配置	效果
max[direct]=0	任何由你的代码导致的弃用都会使测试失败
max[indirect]=999	在过渡期间容忍来自 vendor 代码的弃用
max[total]=0	任何来源的弃用都会使测试失败（最严格的设置）
disabled=1	完全禁用弃用跟踪（不推荐）
generateBaseline=true&baselineFile=./tests/allowed.json	将当前弃用项快照保存到基线文件
baselineFile=./tests/allowed.json	忽略基线中已有的弃用项（逐步收紧的方式）

---

处理第三方 bundle

Bundle 是最常见的升级阻碍。请按以下顺序处理：

1. 检查兼容性：查看每个 bundle 的 composer.json，确认其 Symfony 版本约束
2. 先更新 bundle：在升级 Symfony 版本前运行 composer update
3. 检查 fork：如果某个 bundle 已被弃用，请在 Packagist 上查找仍在维护的 fork
4. 封装高风险依赖：在可能无法跟上更新的 bundle 前添加适配器

对于 bundle 维护者，请使用功能检测，而不是版本检查：

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

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

使用灵活的约束支持多个版本：

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

---

快速参考：主版本升级检查清单

• 通读 UPGRADE-X.0.md
• 升级到当前主版本的最后一个次版本（例如 6.4）
• 将所有第三方 bundle 更新到最新版本
• 配置 SYMFONY_DEPRECATIONS_HELPER，设为 max[direct]=0
• 运行测试套件并修复所有直接弃用
• 使用 Symfony 弃用规则运行 Rector
• 确认测试输出中没有直接弃用
• 将 extra.symfony.require 更新为新的主版本
• 运行 composer update "symfony/*" --with-all-dependencies
• 清除缓存：rm -rf var/cache/*
• 运行 composer recipes:update，直到所有 recipes 都是最新版本
• 运行完整测试套件
• 运行静态分析
• 部署到预发布环境并验证
• 部署到生产环境并监控日志

---

参考文件

参考资料	内容
升级工作流	弃用处理工作流、recipes:update 详解、CI 流水线集成，以及特定版本的迁移说明

---

与其他技能集成

场景	推荐技能
同时升级 PHP 版本和 Symfony	使用 php-upgrade 技能
更新 Composer 依赖项	使用 composer-dependencies playbook 技能
使用 Symfony 组件	使用 frameworks/symfony/ 中的 symfony-components 技能
现代化 PHP 代码模式	从 dirnbauer/webconsulting-skills 安装 php-modernization