symfony-upgrade

Symfony フレームワークのアップグレード

Symfony のアップグレードモデルは、1つの事実に基づいています。新しいメジャーバージョンは、非推奨コードを削除した直前のブランチの最終マイナーバージョンです。まずすべての非推奨項目を修正すれば、メジャーアップグレードは小さな変更になります。

基本原則

原則	意味
まず変更履歴を読む	アップグレードの前に、対象バージョンの UPGRADE-X.Y.md ファイルと、使用している Symfony パッケージの CHANGELOG.md を読みます。組み込みの知識だけに頼らないでください
非推奨項目を先に解消する	次のメジャーバージョンにアップグレードする前に、現在のバージョンの非推奨項目をすべて修正します。Symfony 8.0 は非推奨項目を除いた 7.4 です
マイナーバージョンを順にアップグレードする	6.2 -> 6.3 -> 6.4 のようにアップグレードし、マイナーバージョンを飛ばさないでください。各バージョンで新たな非推奨項目が明らかになるためです
レシピで設定を最新に保つ	アップグレードのたびに composer recipes:update を実行して、設定ファイルを同期します
非推奨項目の数をテストする	SYMFONY_DEPRECATIONS_HELPER を使って、直接の非推奨項目が見つかった場合にビルドを失敗させます
まずバンドルを更新する	サードパーティ製バンドルは最もよくある阻害要因です。Symfony のバージョンを上げる前に更新してください

---

最初に変更履歴を読む

コードに手を加えたりコマンドを実行したりする前に、対象バージョンで何が変更されたかを確認します。

1. docs-lookup スキルを使って、Symfony のアップグレードドキュメントと対象バージョンの UPGRADE-X.Y.md ファイルを取得します（ファイル名には対象バージョンが含まれます。UPGRADE-8.0.md は 7.4 -> 8.0、UPGRADE-8.1.md は 8.0 -> 8.1 を扱います）
2. そのスキルを使わない場合は、Symfony リポジトリから読みます：https://github.com/symfony/symfony/blob/X.Y/UPGRADE-X.Y.md
3. インストール済みのパッケージを確認します。 各 Symfony パッケージには、そのパッケージの非推奨項目と後方互換性を破る変更を記載した vendor/symfony/<package>/CHANGELOG.md が含まれています。UPGRADE-*.md ファイルはそれらのパッケージにはありません。プロジェクトが完全な symfony/symfony パッケージを必要とする場合に限り、vendor/symfony/symfony/ に含まれます。そのため、vendor/symfony/*/UPGRADE-*.md は通常、何にも一致しません
4. **Symfony のブログを確認し、**主な変更点がまとめられたリリース告知を読みます
5. またはユーザーにリリースノートの提供を依頼します

これを省略しないでください。各バージョンには、このスキルではすべてを網羅できない固有の変更があります。UPGRADE ファイルには、何が壊れ、何が非推奨になり、何が削除されたかが正確に記載されています。

---

Symfony のリリースモデル

リリース種別	サイクル	サポート	例
パッチ（X.Y.Z）	毎月	バグ修正のみ	7.4.1 -> 7.4.2
マイナー（X.Y）	6か月ごと（5月と11月）	非推奨項目が追加される場合があります。後方互換性を破る変更はありません	7.3 -> 7.4
メジャー（X.0）	2年ごと（奇数年の11月）	非推奨コードを削除します。後方互換性を破る変更が含まれる場合があります	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 スキルを参照）、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：レシピを更新する

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. 間接的な非推奨機能に対応する：

間接的な非推奨機能は、サードパーティ製バンドルに起因します。対象の 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：レシピを更新する

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

このコマンドは、インストール済みのレシピと最新のレシピとの差分を生成し、git パッチとして適用します。競合は通常の git の競合と同じように解決してください。実行する前に作業内容をコミットしてください。

フェーズ 5：テストする

vendor/bin/phpunit
vendor/bin/phpstan analyse

本番環境の前に、ステージング環境へデプロイしてください。

非推奨機能への対応、SYMFONY_DEPRECATIONS_HELPER のオプション、バンドルの互換性戦略については、アップグレードワークフローのリファレンスを参照してください。

---

SYMFONY_DEPRECATIONS_HELPER のオプション

設定	効果
max[direct]=0	コードに起因する非推奨機能があれば失敗します
max[indirect]=999	移行中、ベンダーコードに起因する非推奨機能を許容します
max[total]=0	発生元を問わず非推奨機能があれば失敗します（最も厳しい設定）
disabled=1	非推奨機能の追跡を完全に無効にします（推奨しません）
generateBaseline=true&baselineFile=./tests/allowed.json	現在の非推奨機能をベースラインファイルに記録します
baselineFile=./tests/allowed.json	すでにベースラインに記録されている非推奨機能を無視します（段階的に基準を厳しくする方式）

---

サードパーティ製バンドルへの対応

バンドルは、アップグレードを妨げる最も一般的な要因です。次の順序で作業してください：

1. 互換性を確認する：各バンドルの composer.json を読み、Symfony のバージョン制約を確認します
2. 先にバンドルを更新する：Symfony のバージョンを上げる前に composer update を実行します
3. フォークを確認する：バンドルが放棄されている場合は、Packagist でメンテナンスされているフォークを探します
4. リスクのある依存関係をラップする：今後メンテナンスされない可能性があるバンドルの前にアダプターを配置します

バンドルのメンテナーは、バージョンチェックではなく機能検出を使用してください：

// 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）
• すべてのサードパーティ製バンドルを最新バージョンに更新する
• 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:update の詳細、CI パイプラインとの統合、バージョン固有の移行に関する注意事項

---

他のスキルとの連携

状況	推奨スキル
Symfony と PHP のバージョンを同時にアップグレードする場合	php-upgrade スキルを使用
Composer の依存関係を更新する場合	composer-dependencies プレイブックスキルを使用
Symfony コンポーネントを扱う場合	frameworks/symfony/ の symfony-components スキルを使用
PHP のコードパターンを最新化する場合	dirnbauer/webconsulting-skills から php-modernization をインストール