php-upgrade

PHP バージョンのアップグレード

マイナーバージョンを一度に 1 つずつアップグレードし、バージョンを飛ばしてはいけません。各ステップで、次のリリースではエラーになる非推奨機能が明らかになります。アップグレードは毎回、監査、自動化、テスト、デプロイという同じサイクルで進めます。

基本原則

原則	意味
まず変更履歴を確認する	各バージョン移行の前に、その移行に関する公式の php.net 移行ガイドを取得します。このスキル内の静的リストやモデルの記憶には決して頼らないでください
バージョンを一度に 1 つずつ進める	8.2 -> 8.3 -> 8.4 -> 8.5 の順にアップグレードします。バージョンを飛ばすと、問題の切り分けができなくなります
アップグレード前に非推奨機能を修正する	バージョン N の非推奨機能はバージョン N+1 でエラーになるため、必須の修正として扱います
まず自動化し、その後に手動で対応する	手作業でコードに変更を加える前に、Rector と PHPCompatibility を実行します。必要な変更の 80% 以上を検出できます
テストで動作を確認する	対象バージョンでテストスイートが通るまでは、アップグレードは完了していません
プラットフォームのバージョンを固定する	composer.json の config.platform.php を、デプロイ先の最低バージョンに合わせて設定します

---

アップグレード手順の概要

フェーズ 0：移行ガイドを読む

コードに手を加える前に、現在のバージョンから対象バージョンまでのすべての移行ステップについて、公式ガイドを読みます。各ステップには個別のページがあり、移行先のバージョンにちなんで migrationXY という名前が付いています。

移行ステップ	ページ
7.4 -> 8.0	https://www.php.net/manual/en/migration80.php
8.4 -> 8.5	https://www.php.net/manual/en/migration85.php

各ガイドにはサブページがあります。migrationXY.incompatible.php（後方互換性のない変更）、migrationXY.deprecated.php、そして該当する場合は migrationXY.removed-extensions.php です。少なくとも最初の 2 つを読みます。

取得方法：

1. docs-lookup スキルを使います。 PHP の場合、Context7 ライブラリ ID /websites/php_net_manual_en に解決されます。「Migrating from PHP X.Y to X.Z, backward incompatible changes and deprecated features」と尋ねます
2. 代替手段： 上記の php.net URL を直接取得するか、ユーザーにリリースノートを依頼します
3. 該当する項目を書き出します。 各項目についてコードベースを grep し、その結果を自動化と手動修正の作業リストとして保存します

「バージョン別の既知の注意点」の表は grep の出発点であり、移行ガイドの代わりではありません。

フェーズ 1：監査

コードを変更する前に、アップグレードの規模を把握します。

1. PHPCompatibility を対象バージョンに対して実行し、互換性のないコードを特定します。 最新の安定版（9.3.5、2019 年）は PHP 8.1 より前にリリースされており、新しいルールのほとんどが含まれていません。PHP 8.x のスニフが含まれる 10.0.0-alpha2 以降をインストールし、まずアップグレードノートを読んでください
2. 対象バージョンの PHP バイナリで php-parallel-lint を実行し、構文エラーを検出します
3. composer outdated を実行し、すべての依存関係が対象バージョンをサポートしているか確認します
4. フェーズ 0 のリストをコードと照合します
5. PHP 拡張機能（ext-intl、ext-mbstring など）の互換性を確認します

フェーズ 2：自動化

Rector を使って、コード変換の大部分を適用します。

// rector.php
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/tests'])
    ->withPhpSets(php85: true);  // adjust to target version

必ず最初にドライランを実行します。

vendor/bin/rector process --dry-run

変更内容を確認してから適用します。

vendor/bin/rector process

Git の履歴を整理した状態に保つため、Rector による変更は手動修正とは分けてコミットします。

フェーズ 3：依存関係を更新する

1. composer.json を新しい PHP バージョン制約に更新します："php": ">=8.5"
2. config.platform.php を対象バージョンに合わせて更新します
3. composer update を実行し、競合を解決します
4. 必要に応じて PHP 拡張機能を更新します

フェーズ 4：テストとデプロイ

1. 新しい PHP バージョンでテストスイート全体を実行します
2. 静的解析（PHPStan/Psalm）を実行します
3. ステージング環境にデプロイして動作を確認します
4. デプロイ後、非推奨機能に関する通知がないか本番環境のログを監視します

ツールの設定、CI パイプラインのセットアップ、Docker に関する考慮事項については、アップグレード手順のリファレンスを参照してください。

---

ツール

ツール	目的	使用するタイミング
Rector	AST ベースのコード変換の自動化	監査後の最初のステップです。機械的な変更の大半を処理します
PHPCompatibility	バージョン間の互換性を確認する PHP_CodeSniffer ルールセット	監査フェーズです。作業を始める前に、互換性のないコードをすべて特定します
php-parallel-lint	並列構文チェック（逐次実行より約20倍高速）	監査フェーズです。新しいバージョンでの構文エラーを検出します
PHPStan/Psalm	静的解析	検証フェーズです。変換後の型エラーを検出します
symfony/phpunit-bridge	テスト出力で非推奨項目の概要を表示	継続的に使用します。アップグレード中の非推奨項目数を追跡します

---

バージョン別の既知の落とし穴

実際のアップグレードで最も頻繁に問題となる項目です。それぞれの項目は、そのバージョン移行に対応する php.net の移行ガイドから引用しています。それ以外の項目については、完全なガイドを取得してください（フェーズ 0）。

移行	落とし穴
7.4 -> 8.0	0 == "abc" は false になります（数値が文字列にキャストされます）。配列、リソース、オブジェクトに対する算術演算は TypeError をスローします。@ では致命的なエラーを抑制できなくなります。未定義の変数、キー、プロパティの読み取りは警告になります。未定義の裸の定数は Error をスローします。create_function() と each() は削除されました。. は + と - よりも優先順位が低くなりました
8.0 -> 8.1	null 非許容の組み込みパラメーターに null を渡すと非推奨になります。精度が失われる float から int への変換は非推奨になります。__serialize() と __unserialize() を持たない Serializable は非推奨になります。継承されたメソッドは、親クラスと static 変数を共有します。false への追加は非推奨になります。$GLOBALS 配列全体への書き込みはエラーになります
8.1 -> 8.2	動的プロパティは非推奨になります（プロパティを宣言するか、#[\AllowDynamicProperties] を追加してください）。"${var}" による補間は非推奨になります。utf8_encode() と utf8_decode() は非推奨になります。"self::method" のような呼び出し可能な値は非推奨になります。strtolower()、ucfirst() などはロケールの影響を受けなくなります
8.2 -> 8.3	空文字列または英数字以外の文字列に対する ++ と -- は非推奨になります。引数なしの get_class() は非推奨になります。Date 拡張機能のエラーは警告ではなく DateError 型と DateException 型になります。静的プロパティを持つトレイトは、親のプロパティを再宣言します。空の配列に負のインデックスを指定すると、次のキーは n+1 になります
8.3 -> 8.4	暗黙的に null 許容となるパラメーター（T $x = null）は非推奨です。?T を使用してください。E_STRICT と E_USER_ERROR を指定した trigger_error() は非推奨になります。exit() は型チェックされます。IMAP、OCI8、PDO_OCI、PSpell は PECL に移動しました。GMP は final です。_ という名前のクラスは非推奨になります。0 ** -1 は非推奨になります
8.4 -> 8.5	Opcache は常に組み込まれるため、zend_extension=opcache.so は警告を出すようになります。php.ini と Docker 設定から削除してください。バッククォート演算子、(boolean)、(integer)、(double)、(binary) のキャスト、null の配列オフセット、case x; は非推奨になります。__sleep() と __wakeup() はソフト非推奨になります。disable_classes INI は削除されました。トレイトは親クラスの前にバインドされます。int に収まらない float のキャストは警告を出すようになります

---

よくある落とし穴

落とし穴	問題となる理由	防止策
バージョンを飛ばす	どの変更が何を壊したのかを特定できなくなります	常に一度に1つのバージョンだけアップグレードしてください
非推奨警告を無視する	次のバージョンでは非推奨の機能が致命的なエラーになります	アップグレード前に、すべての非推奨項目を修正してください
依存関係を確認しない	サードパーティ製パッケージが対象バージョンに対応していない場合があります	開始前に composer outdated を実行し、対応状況を確認してください
--ignore-platform-reqs を使う	安全性チェックを回避し、実行時エラーを引き起こします	絶対に使わないでください。代わりに、実際の制約を修正してください
config.platform.php を固定しない	ローカルの PHP が本番環境と異なるため、インストール時に不整合が生じます	必ず本番環境と一致するように設定してください
Rectorを大規模に実行し、変更をレビューしない	特殊なケースでは、Rectorが誤った変換を行うことがあります	必ず最初にドライランを行い、変更をレビューして、小さな単位で実行してください
PHP拡張を忘れる	バージョン間で拡張の動作が変わったり、非推奨になったりします	アップグレード前に、必要な拡張をすべて確認してください

---

クイックリファレンス：アップグレードチェックリスト

• 対象バージョンのphp.net移行ガイドを確認する
• 対象バージョンに対してPHPCompatibilityスキャンを実行する
• 対象バージョンのPHPバイナリでphp-parallel-lintを実行する
• すべてのComposer依存関係が対象バージョンに対応していることを確認する
• 対象バージョンを設定してRectorを構成し、実行する（最初にドライランを行う）
• Rectorによる変更をレビューし、コミットする
• 残りの問題を手動で修正する
• composer.json のPHP制約と config.platform.php を更新する
• composer update を実行する
• 対象のPHPバージョンでテストスイート全体を実行する
• 静的解析（PHPStan/Psalm）を実行する
• ステージング環境にデプロイして確認する
• 本番環境にデプロイしてログを監視する

---

参考ファイル

参考資料	内容
アップグレードプロセス	ツールの設定、CIパイプラインのセットアップ、Docker戦略、手順に沿ったコマンド

---

他のスキルとの連携

状況	推奨スキル
移行ガイドでバージョン間のアップグレード方法を調べる	docs-lookup スキルを使用する
PHPと併せてSymfonyをアップグレードする	frameworks/symfony/ の symfony-upgrade スキルを使用する
PHPアップグレード後にComposer依存関係を更新する	composer-dependencies スキルを使用する
PHPコードのパターン（DTO、列挙型、厳密な型指定）を最新化する	dirnbauer/webconsulting-skills または netresearch/php-modernization-skill から php-modernization をインストールする
アップグレード後に静的解析を実行する	testing