PHP 8.1.34 から
8.4.27 / 8.5.12 へ

※2026年10月時点の公開情報に基づきます。項目数と内容は、この特集の変更カタログ（全 213 項目）と php.net の移行ガイドから作っています。

このページが当てはまるバージョン

PHP 8.1 系のすべて、8.1.0 から 8.1.34 までの 35 版が対象です。パッチ版（3 つ目の数字）の間では後方互換性が保たれるため、8.1.2 のままのサーバーでも、8.1.27 まで上げてあるサーバーでも、新しい版へ移すときに直す箇所は変わりません。8.1 系のパッチ版の途中で入った変更のうち、コードの修正が要るものは、この特集の資料では把握していません。細かなセキュリティ修正は ChangeLog の各パッチの項を見てください。

8.1 系の最後のリリースは 8.1.34（2025-12-18）で、8.1 系は 2025-12-31 にセキュリティサポートを終えています。8.1.35 以降の番号は出ておらず、php-src にもタグはありません（2026-10-23 に確認）。8.1.35 や 8.1.36 という番号で探してここに来た場合も、8.1 系であればこのページがそのまま当てはまります。

移行先は 2026-10-21 に公開されたセキュリティ修正版の 4 つで、組み合わせごとの項目数は次のとおりです。

• PHP 8.1.34 → PHP 8.4.27：43 項目（削除 4・非推奨 17・挙動変更 22）
• PHP 8.1.34 → PHP 8.5.12：65 項目（削除 5・非推奨 29・挙動変更 31）
• PHP 8.1.34 → PHP 8.3.36：27 項目（削除 2・非推奨 10・挙動変更 15）
• PHP 8.1.34 → PHP 8.2.35：13 項目（削除 1・非推奨 6・挙動変更 6）

8.2・8.3・8.4 を使っている人へ

この特集の起点ページは 8.1 系までです。8.2.x・8.3.x・8.4.x で動かしている場合、今回の脆弱性への対応は同じ系列の 8.2.35 / 8.3.36 / 8.4.27 へのパッチ更新で済み、パッチ更新ではコードの修正は原則要りません。そのうえで次のマイナー版へ上げるときは、このページの一覧のうち、自分の版より後のブロックだけを読めば足ります。下の一覧は、変更が入った版ごとにブロックが分かれているからです。

読み方は 2 段階です。まず「変更の全一覧」の上にある移行先のボタンで、移す先の版を選びます。選んだ版より後のブロックは折りたたまれます。次に、自分の版と同じか、それより前のブロックは読み飛ばします。8.3.x から 8.5.12 へ移すなら、8.5.12 を選んだうえで [8.2] と [8.3] を飛ばし、[8.4] と [8.5] だけを確認します。ボタンの横に出る合計の件数は [8.2] から数えた値なので、上の表の件数と食い違っても気にしなくて構いません。8.2.x を使っている場合は、8.2 系のサポートが 2026-12-31 で終わる点も、移行を急ぐ理由になります。

下の「コーディングエージェントに一括で任せる」のプロンプトは 8.1.34 起点で書いてあります。8.2〜8.4 から使うときは、プロンプトの「8.1.34（8.1 系）」を自分の版に、「8.1 系から」を「8.3 系から」のように書き換え、対象外のブロックを読まないよう一文足してください。

まず結論：どこへ移すか

8.1 起点では、8.4.27 と 8.5.12 のどちらを選んでも筋が通ります。差は 22 項目で、そのうち 12 項目は 8.5 の非推奨、残りは php.ini の扱い（disable_classes の削除、Opcache の組み込み）と、PDO・Intl などの細かな挙動変更です。ここでは 8.4.27 を第一候補として手順を書いていますが、次の条件がそろうなら 8.5.12 へ直行するほうが、次の移行までの時間を 1 年長く取れます。

• 使っているフレームワークと主要なライブラリが、8.5 での動作をリリースノートで明言している（composer why-not php 8.5.12 が何も返さない）
• 本番の php.ini や FPM のプール設定を自分たちで書き換えられる（共用サーバーやマネージドの実行環境で、設定を事業者が持っている場合は 8.4 のほうが無難）
• 8.5 で増える非推奨（バッククォート、(integer) などのキャスト名、$http_response_header など）を、今回の作業でまとめて片付ける時間がある

8.5.12 を選ぶ場合、下の「コーディングエージェントに一括で任せる」の設定例とプロンプトは 8.4.27 を前提に書いてあるので、次の箇所を読み替えてください。プロンプトと Dockerfile の 8.4.27 を 8.5.12 に（FROM php:8.5.12-cli）、8.4 を 8.5 に。PHPStan の設定の phpVersion: 80400 を phpVersion: 80500 に。Rector の設定でコメントにしてある ->withPhpSets(php84: true) を使う場合は php85: true に。PHPCompatibility の testVersion も 8.5 にしますが、PHPCompatibility が 8.5 の変更をどこまで検出できるかは、使う版のリリースノートで確かめてください。

8.1 向けのバックポートは
今回だけの応急処置

2026-10-21 の php.net の勧告は、8.1 以前について「no longer receive updates from the PHP project」と明記しています。そのうえで、深刻度を理由に、PHP セキュリティチームが 7.4・8.0・8.1 向けに「minimal source-backports」を出しました。勧告が想定している利用者は、ソースから自分でビルドする人と、LTS ベンダーを使えない人です。ディストリビューションと LTS ベンダーには事前にパッチが渡っていたとも書かれているので、OS のパッケージで PHP を入れている場合は、まずベンダーの更新を確かめます。

8.1 向けは php-src の PHP-8.1-CVE-2026-109618-109619 ブランチです。2026-10-23 に確認したところ、8.1.34 のタグから 4 コミット進んだだけのブランチで、修正のコミットには「Minimal mitigation for EOL version.」とあり、main/php_version.h は 8.1.34 のままでした。8.1.35 というリリースは存在しません。言い換えると、手元でビルドして入れ替える人のための当て布で、8.1 系の正式な修正版は今後も出ません。

8.1 系は、セキュリティサポートが終わってから 10 か月足らずで今回の勧告を迎えました。次に何か見つかったときにも同じ手当てがあるとは、どこにも約束されていません。今回はバックポートやベンダーの修正で乗り切れたとしても、サポートのある 8.4 か 8.5 へ移しておく必要があります。

この起点で特に危ない変更

8.1 起点の変更は、半分近くが非推奨の通知です。通知はログを見れば見つかるので、ここではそれ以外を中心に選びました。通知も出さずに結果が変わるもの、PHP の外側（php.ini やパスワードのハッシュ、DB の接続）で効いてくるもの、そして件数が多すぎて他の通知を隠してしまうものの 10 件です。

1. 8.2動的プロパティの通知が
   ログを埋め尽くす

   宣言していないプロパティへの代入が非推奨になりました。stdClass と __get() / __set() を実装したクラスは対象外なので、まず通知が出たクラスを一覧にし、宣言を足すのか、#[\AllowDynamicProperties] で当面しのぐのかをクラスごとに決めます。属性で逃がしても PHP 9 で Error になる予定は変わりません。

   → 一覧の該当項目へ

2. 8.2strcmp() が -1 / 0 / 1 しか
   返さなくなる

   strcmp() や strcasecmp() は、これまで差分の値（たとえば 2 や -5）を返すことがありました。8.2 からは -1・0・1 のどれかだけです。< 0 や > 0 で判定していれば影響はありませんが、戻り値を === 2 のように比べたり、差の大きさを使ったりしているコードは黙って判定が変わります。var_export() がクラス名の先頭に \ を付けるようになった点も同じ項目です。

   → 一覧の該当項目へ

3. 8.3range() が
   文字列の数字を別扱いする

   片方が数字の文字列の場合、もう片方も文字として扱われるようになり、range('9', 'A') は数字の並びではなく文字の範囲を返します。フォームやクエリ文字列から受け取った値をそのまま渡していると、型の違いで結果が変わります。step に 0 を渡すと ValueError になる点もあわせて確認します。

   → 一覧の該当項目へ

4. 8.3負のキーの後の [] 追加で
   キーが変わる

   空の配列に $a[-5] = 'x' と入れてから $a[] = 'y' とすると、これまでは 0 番に入っていた値が -4 番に入ります。キーを番号として後から参照しているコードでは、値が見つからなくなるだけで、エラーは出ません。

   → 一覧の該当項目へ

5. 8.4暗黙の nullable が
   大量の Deprecated を出す

   function f(Foo $x = null) の書き方が非推奨になりました。8.1 時代のコードやライブラリにはごく普通にある書き方なので、件数ではこの起点で最も多くなりやすい通知です。?Foo $x = null への書き換えは Rector の ExplicitNullableParamTypeRector でほぼ機械的にできます。

   → 一覧の該当項目へ

6. 8.4bcrypt の既定コストが
   10 から 12 へ

   password_hash() を既定のまま使っていると、既存のハッシュすべてに対して password_needs_rehash() が true を返します。ログインのたびに再ハッシュが走り、1 回あたりの計算量はおよそ 4 倍です。朝の始業時刻のようにログインが集中する時間帯の CPU 使用率を、切り替え前に見積もっておきます。

   → 一覧の該当項目へ

7. 8.4MySQL の切断エラーの
   コードが変わる

   MySQL 8.0.24 以降のサーバーで wait_timeout を超えて切断されたとき、エラーコードが 2006 ではなく 4031 になります。長時間動くバッチやワーカーで、2006 を見て再接続する処理を書いていると、その分岐に入らなくなります。

   → 一覧の該当項目へ

8. 8.5disable_classes が
   黙って効かなくなる

   8.5 で disable_classes の INI 設定そのものが削除されました。php.ini に残した行で特定のクラスを使えなくしていた場合、その制限は 8.5 では働きません。8.5.12 を選ぶなら、php.ini から行を消すだけでなく、制限が必要だった理由に合った別の手段を用意します。

   → 一覧の該当項目へ

9. 8.5Opcache が本体に組み込まれ、
   読み込みの行が警告になる

   8.5 では Opcache が常に組み込まれた状態で動きます。8.1 時代の php.ini や conf.d にある zend_extension=opcache.so の行は警告の原因になるので削除します。opcache.enable などの設定はこれまでどおり効きます。

   → 一覧の該当項目へ

10. 8.5$http_response_header
    などが非推奨に

    file_get_contents('http://...') の後に自動で作られる $http_response_header が非推奨になりました。8.4 で追加された http_get_last_response_headers() に置き換えます。同じ 8.5 では、バッククォート演算子と、(integer) や (boolean) などのキャスト名も非推奨です。

    → 一覧の該当項目へ

起点から移行先までに入った
変更の全一覧

8.1 系から 8.5 までに入った削除・非推奨・挙動変更を、入った版ごとの 4 つのブロック（[8.2]〜[8.5]）で並べています。一覧は累積です。8.4.27 へ移すなら [8.2]〜[8.4]、8.5.12 へ移すなら 4 つすべてを確認します。8.2〜8.4 を使っている人は、上の表のとおり自分の版より後のブロックだけを読んでください。

区分の意味は次のとおりです。削除は Fatal error や Error 例外になるもの、または機能・拡張そのものが無くなるもの。非推奨は E_DEPRECATED の通知が出るものの動作は続くもの。挙動変更はエラーを出さずに結果やエラーの種類が変わるもの。各項目の id（v84-02 など）は、エージェントへの指示や作業記録で使えます。

※以下の一覧に載せたコード・コマンド・プロンプトはあくまで例です。最終確認は php.net の公式 ChangeLog・移行ガイドで行ってください。内容の利用により生じた損害について当方は責任を負いません（詳しくはページ末尾の免責事項）。

作業の進め方

8.1 起点では、コードの書き換えそのものより「8.4 と 8.5 のどちらで動かすか」を早く決め、設定ファイルと通知の後始末を確実に終えることが作業の中心になります。以下はリポジトリの直下で、Docker が使える端末から実行する前提で書いています。

1. 8.4.27 と 8.5.12 の両方で、まず構文だけ通す

移行先を決める材料として、最初に両方の版で構文チェックと依存関係の確認をします。php -l は実行せずに構文だけを見るので、DB や拡張が無いコンテナでも動きます。8.1 で書いたコードが構文で落ちることはまれですが、8.4・8.5 で増えた組み込み関数と同じ名前の自作関数（array_find() や array_first() など）は、ここではなく実行時に Fatal error になる点に注意してください。

for v in 8.4.27 8.5.12; do
  echo "== PHP $v"
  docker run --rm -v "$PWD":/app -w /app php:$v-cli sh -c \
    "find . -path ./vendor -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l | grep -v '^No syntax errors'"
  docker run --rm -v "$PWD":/app -w /app composer:2 composer why-not php $v
done

# 8.4 / 8.5 で追加された関数と同じ名前の自作関数が無いか
grep -rnE 'function\s+(array_find|array_find_key|array_any|array_all|array_first|array_last|mb_trim|mb_ucfirst)\s*\(' \
  --include='*.php' --exclude-dir=vendor .

composer why-not php 8.5.12 がフレームワークや主要なライブラリの名前を返したら、今回は 8.4.27 にしておくのが現実的です。8.4.27 でも名前が返るなら、そのパッケージの更新が移行の前提作業になります。

2. php.ini と FPM の設定を点検する

8.1 起点の変更のうち、コードではなく設定ファイルで効くものがいくつかあります。8.5.12 へ移すなら disable_classes と Opcache の読み込み行、8.4 以降ではセッション ID の長さなどの INI が非推奨です。サーバーの設定ディレクトリと、リポジトリに入れている設定の両方を探します。

grep -rnE '^\s*(disable_classes|zend_extension\s*=\s*.*opcache|session\.(sid_length|sid_bits_per_character|use_trans_sid|use_only_cookies))' \
  /etc/php* /usr/local/etc/php docker/ 2>/dev/null

見つかった disable_classes は、何のために置いたのかを先に確かめます。8.5 では行が残っていても何も起きず、制限だけが消えるからです。Opcache の行は 8.5 では消すだけで構いません。設定は 8.1 のファイルを持ち込まず、移行先の php.ini-production から作り直して、必要な値だけを書き写すほうが漏れが出にくくなります。

3. 暗黙の nullable は単独の規則で先に片付ける

Rector の PHP 8.4 向けのセットには、暗黙の nullable を直す ExplicitNullableParamTypeRector のほかに、foreach を array_find() などへ置き換える規則も入っています。後者は動作を直す変更ではないので、最初は暗黙の nullable の規則だけを当て、差分を小さく保ってコミットします。セット全体を当てるかどうかは、その後で決めれば十分です。

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;
use Rector\Php84\Rector\Param\ExplicitNullableParamTypeRector;

return RectorConfig::configure()
    ->withPaths([__DIR__ . '/src', __DIR__ . '/app'])
    ->withRules([ExplicitNullableParamTypeRector::class]);

composer require --dev rector/rector phpcompatibility/php-compatibility
vendor/bin/rector process --dry-run
vendor/bin/rector process
git commit -am "PHP 8.4: 暗黙の nullable を明示的な ?T に書き換え"

# 8.1 でも 8.4 でも動く書き方かを確認
vendor/bin/phpcs -ps . --standard=PHPCompatibility --runtime-set testVersion 8.1-8.4 --ignore=*/vendor/*

8.5.12 へ進む場合、Rector の PHP 8.5 向けセットには、バッククォートを shell_exec() に、(integer) を (int) に、case 1; を case 1: に直す規則が含まれています。8.5 の非推奨のうち機械的に直せるものは、このセットでまとめて片付けられます。

4. ステージングで Deprecated を全件集める

このページの非推奨は、8.4.27 まででも 17 項目あります。テストが十分にあれば CLI で流してログを取れますが、画面からしか通らない処理が多いなら、ステージングの PHP-FPM のプール設定で通知をすべてログへ出し、普段の操作を一通り流すほうが確実です。php_admin_value で設定すると、アプリケーション側の ini_set() や error_reporting() で上書きされません。

; -1 はすべての通知を報告する指定（E_ALL を含む）
php_admin_value[error_reporting] = -1
php_admin_flag[display_errors] = off
php_admin_flag[log_errors] = on
php_admin_value[error_log] = /var/log/php/upgrade-deprecated.log

LOG=/var/log/php/upgrade-deprecated.log

# vendor/ の外（自分たちで直す分）を、通知の種類ごとに
grep 'PHP Deprecated' "$LOG" | grep -v '/vendor/' \
  | sed -E 's/^\[[^]]*\] PHP Deprecated: +//; s/ in \/.* on line [0-9]+$//' \
  | sort | uniq -c | sort -rn | head -30

# vendor/ の中（パッケージの更新で消す分）を、パッケージごとに
grep 'PHP Deprecated' "$LOG" | grep -oE '/vendor/[^/]+/[^/]+/' \
  | sort | uniq -c | sort -rn

vendor/ の中から出ている通知は、手で直さずにパッケージの更新で消します。ログに通知が 1 件も出ないときは、設定を足したプールを再起動したか、phpinfo() の error_reporting と error_log にプール設定の値が出ているかを確かめてください。

5. bcrypt と DB 接続は、数字で確かめる

8.4 の bcrypt の既定コストの変更は、コードの差分には現れず、負荷として現れます。コスト 10 と 12 で 1 回のハッシュにかかる時間を移行先のコンテナで測り、ログインが集中する時間帯の件数を掛けて、CPU に余裕があるかを見積もります。余裕が無ければ、password_hash() と password_needs_rehash() の両方に ['cost' => 10] を明示して据え置きます。

docker run --rm php:8.4.27-cli php -r '
foreach ([10, 12] as $c) {
  $t = microtime(true);
  for ($i = 0; $i < 20; $i++) { password_hash("test-password", PASSWORD_BCRYPT, ["cost" => $c]); }
  printf("cost %d: %.1f ms/回\n", $c, (microtime(true) - $t) / 20 * 1000);
}'

MySQL の切断エラーのコード（2006 と 4031）と、exit() の関数化は、grep で該当箇所を探して目で確かめます。exit() は 8.4 で関数と同じ扱いになったため、配列などを渡している箇所や、declare(strict_types=1) のファイルで文字列以外を渡している箇所が TypeError になります。

grep -rnE '\b2006\b|CR_SERVER_GONE_ERROR|server has gone away' --include='*.php' --exclude-dir=vendor .
grep -rnE '\b(exit|die)\s*\(\s*\$' --include='*.php' --exclude-dir=vendor .
grep -rnE "\brange\s*\(\s*['\"\$]" --include='*.php' --exclude-dir=vendor .

6. 切り替えは、ログの件数を見ながら

ステージングで 4. のログが 0 件（vendor/ の分は更新で消えた状態）になり、5. の見積もりに問題が無ければ本番を切り替えます。8.1 系は修正版が出ない状態なので、切り替えを先延ばしにする理由はあまりありません。切り替え後もしばらくは log_errors を有効にしたまま、E_DEPRECATED と E_WARNING の件数を日ごとに見ておくと、テストで通らなかった経路の問題を拾えます。

コーディングエージェントに一括で任せる

このページの一覧は、人が読むチェックリストであると同時に、Claude Code や Codex にそのまま渡せる作業指示の材料でもあります。8.1 系から 8.4.27 までの変更は項目数が多いので、全部を手で追うより、機械で拾えるものは静的解析と Rector に任せ、エージェントには「一覧と突き合わせて残りを探し、直した理由を項目 id で説明する」ところまでを頼むのが現実的です。

ただし、エラーを出さずに結果だけが変わる種類の変更は、ツールでもエージェントでも見落としが出ます。この節の最後にある「検収で人が見るところ」は、エージェントの報告を受け取ったあとに必ず人が確認してください。

※ツール名・設定の書き方・コマンドは、2026年10月時点の各公式ドキュメントで確認したものです。

任せる前に用意しておくもの

• 作業ブランチ。git switch -c php-upgrade-8.4 のように移行専用のブランチを切り、エージェントには main を直接触らせない。
• 今の動きを記録したテスト。テストが無いなら、移行前（8.1.34 のサーバーやステージング）で主要な画面・API・バッチの出力を保存しておく。移行後に同じ入力で比べられれば十分で、立派なテストでなくて構いません。
• 移行先の PHP を動かすコンテナ。Docker の公式イメージには php:8.4.27-cli のようにパッチ版まで固定したタグがあります。ホストの PHP ではなく、このコンテナで解析とテストを動かします。
• 参照資料の保存。このページを docs/php-upgrade/reference.html として保存しておくと、エージェントがネットワークに出られない設定でも一覧を読めます。

FROM php:8.4.27-cli
RUN apt-get update && apt-get install -y --no-install-recommends git unzip \
    && rm -rf /var/lib/apt/lists/*
# アプリが使う拡張をここで足す（例: MySQL）
RUN docker-php-ext-install pdo_mysql mysqli
COPY --from=composer/composer:2-bin /composer /usr/bin/composer
WORKDIR /app

git switch -c php-upgrade-8.4
mkdir -p docs/php-upgrade
curl -sL -o docs/php-upgrade/reference.html "https://shinichi.noguchi.jp.net/feature/phpupgrade/8.1.html"
docker build -t php-upgrade:8.4.27 docker/php-upgrade
# 以降のコマンドはこのコンテナの中で動かす
docker run --rm -it -v "$PWD":/app php-upgrade:8.4.27 bash

機械的に洗い出す道具

エージェントに頼む前に、決まった規則で拾える変更はツールで拾っておきます。エージェントにもこれらを実行させ、その結果を作業の起点にさせると、読み落としが減ります。

PHPCompatibility は、README が案内する 10 系を入れます。安定版の最新 9.3.5 は 2019年12月の版で、PHP 8.0 の正式リリースより前のものです。10 系は2026年10月時点でまだプレリリース（10.0.0-alpha2）で、PHP 7.2 以上と PHP_CodeSniffer 4.0.2 以上が必要です。古いアプリの composer.json に入れると依存が衝突することがあるので、その場合は tools/ のような別ディレクトリに解析用の composer.json を作って入れてください。

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcompatibility/php-compatibility:"^10.0.0@dev"
# 移行先だけで動けばよい場合
vendor/bin/phpcs -ps . --standard=PHPCompatibility --runtime-set testVersion 8.4 --ignore=*/vendor/*
# 切り替えの間、旧版と移行先の両方で動かす必要がある場合は範囲で指定する
vendor/bin/phpcs -ps . --standard=PHPCompatibility --runtime-set testVersion 8.1-8.4 --ignore=*/vendor/*

Rector は、composer.json の "php" 指定から移行先を読ませる書き方が公式の推奨です。先に composer.json の require.php を ^8.4 にしてから、引数なしの withPhpSets() を使います。composer.json をまだ変えられないときは、名前付き引数で版を 1 つだけ指定します（名前付き引数なので、Rector は PHP 8.0 以上で動かします）。差分が大きすぎて読めない場合は、規則を安全なものから 1 つずつ足していく withPhpLevel(0) から始め、数字を 1 ずつ上げる方法も公式に用意されています。

<?php

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
        __DIR__ . '/public',
    ])
    // composer.json の "require": {"php": "^8.4"} を読み、その版までの規則をまとめて適用する
    ->withPhpSets();
    // composer.json を先に変えられない場合は、上の行の代わりに版を 1 つだけ指定する
    // （8.4 なら php84、8.5 なら php85。withPhpSets() は 1 回しか呼べない）
    // ->withPhpSets(php84: true);

composer require rector/rector --dev
vendor/bin/rector process --dry-run   # 差分を見るだけ
vendor/bin/rector process             # 確認してから適用

PHPStan は、phpVersion を指定しないと PHPStan を動かしている PHP の版が前提になります。移行先のコンテナで動かすならそのままでも合いますが、設定ファイルに書いておくほうが取り違えがありません。古いコードにいきなり高いレベルを当てると指摘が多すぎて読めないので、0 から始めて上げていきます。

parameters:
    level: 0
    phpVersion: 80400 # PHP 8.4。8.5 なら 80500
    paths:
        - src
        - public

Claude Code に頼む

Claude Code は、リポジトリ直下の CLAUDE.md を毎回読み込みます。移行の間だけ守らせたい約束をここに書いておくと、指示のたびに繰り返さずに済みます。

## PHP 移行のルール（8.1.34 → 8.4.27）

- 参照資料は https://shinichi.noguchi.jp.net/feature/phpupgrade/8.1.html（保存版: docs/php-upgrade/reference.html）。8.1 系から 8.4 までに入った削除・非推奨・挙動変更の一覧で、各項目に id（例: v80-05）がある。
- 実行・解析・テストは Docker の php-upgrade:8.4.27 イメージ（docker/php-upgrade/Dockerfile）で行う。ホストの php は使わない。
- 変更の根拠は、参照資料の項目 id で示す。
- 1 コミットに 1 種類の変更。Rector の自動変換と手作業の修正を同じコミットに混ぜない。
- @ 演算子、error_reporting の変更、空の catch で警告やエラーを隠さない。
- テストの期待値を変えるときは、変える理由を必ず報告する。
- vendor/ 配下は編集しない。依存パッケージは composer で更新する。
- 次の作業の前には止まって確認を求める: composer.json の require の変更、DB のスキーマ・文字コードに関わる変更、php.ini・.htaccess・FPM 設定など本番環境の設定の変更、業務上の計算結果が変わりうる修正。

一括依頼のプロンプトです。段階ごとに止まって報告させる形にしています。一度に最後まで走らせると、途中の判断を人が確かめる機会がなくなるためです。

このリポジトリの PHP を 8.1.34（8.1 系）から 8.4.27 へ移行します。CLAUDE.md（Codex の場合は AGENTS.md）の移行ルールに従ってください。

参照資料: https://shinichi.noguchi.jp.net/feature/phpupgrade/8.1.html（保存版: docs/php-upgrade/reference.html）
参照資料の「起点から移行先までに入った変更の全一覧」が、8.1 系から 8.4 までに入った削除・非推奨・挙動変更のチェックリストです。移行先 8.4.27 より新しい版のブロックは対象外です。各項目の id（例: v80-05）を作業記録に使ってください。

作業は次の 6 段階で進め、段階ごとに止まって報告してください。私の返事があるまで次の段階に進まないでください。

① インベントリ
- composer.json と composer.lock、使っている PHP 拡張、php.ini の設定に依存している箇所、PHP ファイルの数、テストの有無と実行方法を調べ、docs/php-upgrade/inventory.md にまとめる。
- composer why-not php 8.4.27 と composer outdated --direct を実行し、移行先で動かない依存パッケージと、その更新先の版を一覧にする。
- この段階ではコードを変更しない。

② Rector による自動変換
- rector.php を用意し、vendor/bin/rector process --dry-run の差分を規則ごとに要約して見せる。
- 私が承認した規則だけを適用する。規則ごとにコミットを分け、コミットメッセージに規則名を入れる。

③ 参照資料の一覧との突き合わせ
- 一覧の項目を上から順に 1 つずつ取り上げ、該当しそうな関数名・定数名・INI 名・構文をリポジトリ全体から grep で探す（vendor/ は除く）。
- 結果を docs/php-upgrade/checklist.md に表で残す。列は「項目 id・区分・内容・該当箇所（ファイル:行）・対応（該当なし／修正済み／要判断）」。全項目を 1 行ずつ埋め、飛ばさない。
- エラーにならず結果だけが変わる挙動変更（== の比較、文字コードの既定値、round() や range() の結果など）は、直す前に「要判断」として私に見せる。

④ Deprecated と警告の全件収集
- php-upgrade:8.4.27 のコンテナで error_reporting=E_ALL、display_errors=stderr、log_errors=On にしてテストと主要な画面・バッチを動かし、E_DEPRECATED・E_WARNING・E_NOTICE を全件ログに出す。
- 1 件ずつ原因を直し、最後にログが 0 件になったことをログの実物で示す。@ 演算子や error_reporting の変更で隠すことは禁止。

⑤ テスト
- 既存のテストと、移行前の出力を記録したスモークテストを移行先で実行し、移行前と結果が一致することを確かめる。一致しないものは差分をそのまま見せる。
- vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4 と vendor/bin/phpstan analyse を実行し、残った指摘を一覧にする。

⑥ 変更報告
- 変更内容を表で報告する。列は「項目 id・ファイル・変更前・変更後・理由・テストで確認したか」。
- 自信のない変更、業務ロジックの意味が変わりうる変更、DB や文字コードに関わる変更は別の表に分け、「人の確認が必要」と明記する。

差分ができたら、作業した会話とは別のセッションでレビューさせます。同じ会話の中だと、自分が下した判断をそのまま追認しがちだからです。

これは PHP 8.1.34 から 8.4.27 への移行作業の差分です。git diff main...HEAD を読み、レビューしてください。参照資料: https://shinichi.noguchi.jp.net/feature/phpupgrade/8.1.html（保存版: docs/php-upgrade/reference.html）

次の観点で問題のある箇所を探し、「ファイル:行・問題・根拠になる参照資料の項目 id・修正案」の表で返してください。観点ごとに、問題がなければ「なし」と書いてください。

1. 変更の前後で結果が変わる箇所: == と === の置き換え、文字列と数値の比較、round()・range()・文字列関数の戻り値、PDO で取得した値の型
2. 内部関数に null が渡る箇所を、(string) などのキャストや ?? '' で黙らせていないか。本来 null が来ないはずの値なら、null が来る原因の側を直すべき
3. 動的プロパティを #[\AllowDynamicProperties] で逃がしていないか。逃がした場合はその理由が書かれているか
4. @ 演算子、error_reporting の変更、空の catch で警告やエラーを隠していないか
5. 文字コード: htmlspecialchars() の既定値、mb_* の内部エンコーディング、DB 接続の charset が移行前と同じ結果になるか
6. テストが変更箇所を実際に通っているか。期待値を書き換えて通しただけのテストがあれば指摘する

コードは変更せず、レビュー結果だけを返してください。

非対話で動かす場合は claude -p を使います。段階を区切って 1 段階ずつ実行し、出力を人が読んでから次を流します。--allowedTools に挙げたツールは確認なしで使われるので、最初は読み取りと書き出しだけに絞っておくと安全です。

# ③の突き合わせだけを、コードを変更させずに実行する
claude -p "docs/php-upgrade/reference.html の変更一覧（8.1 系から 8.4 まで）を上から 1 項目ずつ取り上げ、リポジトリ（vendor/ を除く）を grep して該当箇所を探し、docs/php-upgrade/checklist.md に「項目 id・区分・内容・該当箇所・対応」の表で書いてください。コードは変更しないでください。" \
  --allowedTools "Read,Grep,Glob,Write"

# 差分のレビュー（レビュー用プロンプトを docs/php-upgrade/review-prompt.md に保存しておく）
git diff main...HEAD | claude -p "$(cat docs/php-upgrade/review-prompt.md)" > docs/php-upgrade/review.md

レビュー役は、サブエージェントとして定義しておくと何度でも同じ観点で呼び出せます。.claude/agents/ に置いたファイルはチームで共有できます。

---
name: php-upgrade-reviewer
description: PHP 8.1.34 から 8.4.27 への移行差分をレビューする。移行作業のコミット後や PR 作成前に使う。
tools: Read, Grep, Glob, Bash
---

あなたは PHP の版移行のレビュー担当です。git diff main...HEAD を読み、docs/php-upgrade/reference.html の変更一覧（8.1 系から 8.4 まで）と照らして、次を確認してください。

1. 変更の前後で結果が変わる箇所（== と ===、文字列と数値の比較、round()・range()、PDO の取得値の型）
2. null を内部関数に渡す箇所をキャストで黙らせていないか
3. 動的プロパティを #[\AllowDynamicProperties] で逃がしていないか
4. @ 演算子・error_reporting の変更・空の catch で警告を隠していないか
5. 文字コードの既定値の変化が結果に出ていないか
6. 期待値を書き換えただけのテストがないか

結果は「ファイル:行・問題・根拠の項目 id・修正案」の表で返し、コードは変更しないこと。

hooks を使うと、Claude Code がファイルを編集するたびに PHPStan を走らせ、指摘をその場で Claude に返せます。PostToolUse の hook が終了コード 2 で終わると、標準エラーの内容が Claude に渡されます（編集そのものは取り消されません）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/phpstan-changed.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# 編集されたファイルのパスを標準入力の JSON から取り出す（jq が必要）
file=$(jq -r '.tool_input.file_path // empty')
case "$file" in
  *.php) ;;
  *) exit 0 ;;
esac
project="$(cd "$(dirname "$0")/../.." && pwd)"
rel="${file#"$project"/}"
out=$(docker run --rm -v "$project":/app php-upgrade:8.4.27 \
  vendor/bin/phpstan analyse --no-progress --error-format=raw "$rel" 2>&1)
if [ $? -ne 0 ]; then
  echo "$out" >&2
  exit 2
fi
exit 0

Codex に頼む

Codex は AGENTS.md を読みます。リポジトリのルートから作業ディレクトリまでの各階層の AGENTS.md が順に結合され、作業場所に近いものが優先されます。内容は CLAUDE.md の移行ルールと同じで構いません。

# AGENTS.md

## このリポジトリで進めている作業
PHP を 8.1.34（8.1 系）から 8.4.27 へ移行している。
参照資料: https://shinichi.noguchi.jp.net/feature/phpupgrade/8.1.html（保存版: docs/php-upgrade/reference.html）。8.1 系から 8.4 までに入った削除・非推奨・挙動変更の一覧で、各項目に id（例: v80-05）がある。

## 実行環境
- 解析とテストは Docker の php-upgrade:8.4.27 イメージで行う（docker/php-upgrade/Dockerfile）。ホストの php は使わない。
- 静的解析: vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4 --ignore=*/vendor/* .
- 静的解析: vendor/bin/phpstan analyse
- 自動変換: vendor/bin/rector process --dry-run で差分を確認してから適用する

## 守ること
- 変更の根拠は参照資料の項目 id で示す。
- 1 コミットに 1 種類の変更。Rector の自動変換と手作業の修正を混ぜない。
- @ 演算子、error_reporting の変更、空の catch で警告を隠さない。
- テストの期待値を変えたときは理由を報告する。
- vendor/ 配下は編集しない。
- composer.json の require、DB のスキーマや文字コード、php.ini などの本番設定に関わる変更は行わず、提案として報告に書く。

codex exec は非対話で動き、既定では読み取り専用のサンドボックスで実行されます。ファイルを書き換えさせるときは --sandbox workspace-write を付けます。上の一括依頼プロンプトを docs/php-upgrade/prompt.md に保存し、段階を指定して流します。

# ①インベントリだけ（読み取り専用のまま。最後の報告を -o でファイルに残す）
codex exec -o docs/php-upgrade/01-inventory-report.md \
  "docs/php-upgrade/prompt.md を読み、①インベントリだけを実行して結果を報告してください。①以外の段階には進まないでください。"

# ③突き合わせ（checklist.md を書かせるので workspace-write）
codex exec --sandbox workspace-write -o docs/php-upgrade/03-checklist-report.md \
  "docs/php-upgrade/prompt.md を読み、③参照資料の一覧との突き合わせだけを実行してください。コードは変更せず、docs/php-upgrade/checklist.md だけを書いてください。"

# プロンプト全体を標準入力から渡すこともできる
cat docs/php-upgrade/prompt.md | codex exec --sandbox workspace-write -

MCP サーバーとプラグイン

必須ではありませんが、次のものは移行作業で役に立ちます。どれも公式のリポジトリかドキュメントで存在と導入方法を確認できたものだけを載せています。Claude Code 向けには、Anthropic の公式プラグインマーケットプレイス（claude-plugins-official）に PHP 向けのプラグインもあります。

Context7・GitHub・Playwright・Serena・Laravel Boost は、同じ公式マーケットプレイスの外部プラグイン（external_plugins）としても登録されています。外部プラグインの中身は Anthropic が検証したものではない、と README に書かれているので、入れる前に各プロジェクトのページを確認してください。

検収で人が見るところ

エージェントの報告が「テストはすべて通過」でも、次の項目は人が差分と実際の出力を見て確かめます。どれもエラーを出さずに結果だけが変わる種類のものです。

• == による比較。PHP 8.0 で数値と数値でない文字列の比較規則が変わり、0 == "a" が true から false になった。switch や in_array() の判定も同じ影響を受ける。
• 文字コードの既定値。htmlspecialchars() などの既定の文字コードやフラグの変化、mb_* の内部エンコーディング、DB 接続の charset。
• round() と range() の結果。金額や件数の端数処理、ページ送りの範囲を、移行前の出力と突き合わせる。
• PDO で取得した値の型。文字列で返っていた数値が int や float で返るようになると、=== の比較や JSON の出力が変わる。
• 内部関数に null を渡している箇所。キャストで警告を消しただけになっていないか。
• 動的プロパティ。#[\AllowDynamicProperties] で逃がした箇所が、本当にそのままでよいか。
• E_DEPRECATED がゼロであること。エージェントの報告ではなく、移行先のコンテナで error_reporting=E_ALL にして取ったログの実物で確認する。

公式の移行ガイド

8.1 系から 8.5 までに経由する各版の、php.net の移行ガイドと php-src の UPGRADING です。8.2〜8.4 から上げる場合は、自分の版より後のものだけを見れば足ります。

• PHP 8.2：移行ガイド（日本語） ／ 後方互換性のない変更 ／ 非推奨 ／ その他の変更 ／ ChangeLog 8.2.0 ／ UPGRADING
• PHP 8.3：移行ガイド（日本語） ／ 後方互換性のない変更 ／ 非推奨 ／ その他の変更 ／ ChangeLog 8.3.0 ／ UPGRADING
• PHP 8.4：移行ガイド（日本語） ／ 後方互換性のない変更 ／ 非推奨 ／ 削除された拡張モジュール ／ その他の変更 ／ ChangeLog 8.4.0 ／ UPGRADING
• PHP 8.5：移行ガイド（日本語） ／ 後方互換性のない変更 ／ 非推奨 ／ その他の変更 ／ ChangeLog 8.5.0 ／ UPGRADING
• 起点 8.1.34 の ChangeLog：https://www.php.net/ChangeLog-8.php#8.1.34
• 移行先の ChangeLog：8.4.27 ／ 8.5.12 ／ 8.3.36 ／ 8.2.35
• 2026-10-21 のセキュリティ勧告：php.net News Archive 2026 ／ 8.1 向けソースバックポート：PHP-8.1-CVE-2026-109618-109619
• Rector の PHP 8.4 / 8.5 向けセットの中身：php84.php ／ php85.php

※2026年10月時点の公開情報に基づきます。バックポートのブランチの中身（版番号、コミット）と Rector のセットの中身は、2026-10-23 に各リポジトリで確認しました。