【2026年版】PHPCompatibilityの使い方｜PHP 5・7から8へのバージョンアップで問題の箇所を一覧にする

はじめに

「PHPCompatibility」は、PHP のバージョンアップで問題になりそうな箇所を、ファイル名と行番号つきで一覧にしてくれるツールです。削除された関数、使えなくなった書き方、非推奨になった機能などを、ソースコードを読んで見つけてくれます。

2026 年 10 月に PHP で深刻度「緊急」の脆弱性が見つかり、PHP 5 系・7 系には公式の修正版が出ませんでした。古い PHP のシステムを 8 系に上げるとき、最初に「どこを直せばいいか」を洗い出すのに使えます。この記事では、インストールから結果の読み方まで、順番に説明します。

バージョンアップ全体の流れは、PHP 5 系から 8 系へ・PHP 7 系から 8 系への記事にまとめています。

php7cc との違い

PHP 5 から 7 への移行では「php7cc」というツールもよく使われてきました（php7ccのすすめ）。ただし php7cc は開発が止まっていて、調べられるのも PHP 7.0 への移行までです。これから始めるなら PHPCompatibility がおすすめです。

しくみ

• PHPCompatibility は、コードの書き方をチェックするツール「PHP_CodeSniffer（phpcs）」に追加するルール集です。単体のツールではなく、phpcs を通して使います
• コードを実行せずに読むだけ（静的解析）なので、本番のサーバーやデータベースが無くても調べられます
• 新しい PHP（7.2 以上）で動かして、古いコードを読ませます。古い PHP 5 のサーバーの上で動かす必要はありません。手元の PC や Docker で動かしましょう

準備

• PHP 7.2 以上（できれば 8.4 など新しいもの）。php -v で確かめます
• Composer（PHP のパッケージ管理ツール）。composer --version で確かめます。入っていなければ公式サイトから入れます
• 調べたいソースコード一式

ツール専用のフォルダに入れるのがおすすめ

公式の説明では、調べたいプロジェクトに composer require --dev で入れる方法が紹介されています。ただ、古いシステムでは composer.json が古い PHP 向けに書かれていて、入れるときにぶつかることがあります。調べるためだけのフォルダを別に作って入れ、そこから古いコードを指定して調べるのが手軽です。

インストール

# ツール専用のフォルダを作る
mkdir phpcompat-tool
cd phpcompat-tool

# phpcs が PHPCompatibility を自動で見つけるためのプラグインを許可する
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

# PHPCompatibility を入れる（PHP_CodeSniffer なども一緒に入る）
composer require --dev phpcompatibility/php-compatibility:"^10.0.0@dev"

最初の composer config の行が無いと、Composer が「プラグインを許可していない」と止まることがあります。@dev は、開発中の最新版（10 系）を入れる指定で、公式の手順どおりです。

入ったか確かめる

vendor/bin/phpcs -i

「The installed coding standards are ...」のあとに PHPCompatibility が出ていれば準備完了です。

Windows の PowerShell では、vendor/bin/phpcs を vendor\bin\phpcs に読み替えてください（以下すべて同じ）。

まず動かしてみる

調べたいソースが C:\work\old-app（Linux なら /home/user/old-app）にあるとして、PHP 8.4 で問題になる箇所を調べます。

vendor/bin/phpcs -p -s --standard=PHPCompatibility --runtime-set testVersion 8.4 --extensions=php,inc --ignore=*/vendor/* /home/user/old-app

長いので、それぞれの指定の意味です。

• -p：進み具合を表示する（ファイルが多いと時間がかかるので付けておく）
• -s：それぞれの指摘に、ルールの名前（スニフの名前）を付けて表示する。あとで除外するときに使う
• --standard=PHPCompatibility：PHPCompatibility のルールで調べる
• --runtime-set testVersion 8.4：PHP 8.4 で動くかを調べる（次の章で説明）
• --extensions=php,inc：調べるファイルの拡張子。.inc などを使っていれば足す
• --ignore=*/vendor/*：Composer で入れたライブラリ（vendor）は調べない。ライブラリは自分で直すのではなく、新しいバージョンに上げるため

testVersion の指定

testVersion は「どの PHP で動かしたいか」の指定です。書き方は 3 通りあります。

testVersion を指定しないと、非推奨・削除された機能しか知らせてくれません。必ず指定しましょう。

PHP 5 から 8 に上げるときは、先に 7.4 で調べて直し、次に 8.4 で調べる 2 段階にすると、一度に出る指摘が減って進めやすくなります。

結果の読み方

結果は、ファイルごとに次のような形で出ます（例です。メッセージの文言は、ツールのバージョンで少し違います）。

FILE: /home/user/old-app/lib/db.php
----------------------------------------------------------------------
FOUND 2 ERRORS AND 1 WARNING AFFECTING 3 LINES
----------------------------------------------------------------------
 12 | ERROR   | Extension 'mysql_' is deprecated since PHP 5.5 and
    |         | removed since PHP 7.0; Use mysqli instead
 30 | ERROR   | Function each() is deprecated since PHP 7.2 and
    |         | removed since PHP 8.0; Use a foreach loop instead
 45 | WARNING | Function utf8_encode() is deprecated since PHP 8.2
----------------------------------------------------------------------

• 左の数字は行番号です
• ERROR：指定したバージョンでは削除されていて動かないもの。必ず直します
• WARNING：非推奨（今は動くが、将来削除される）もの。余裕があれば直します
• メッセージの「since PHP 7.0」などで、どのバージョンで変わったかがわかります。「Use ... instead」は代わりの書き方の案内です

まずは ERROR を 0 にすることを目標にしましょう。WARNING だけを消したいときは -n を付けると、ERROR だけが表示されます。

結果を集計・保存する

ファイルが多いと、画面では追いきれません。目的に合わせて出し方を変えましょう。

全体の規模をつかむ（集計）

# ファイルごとの件数
vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4 --ignore=*/vendor/* --report=summary /home/user/old-app

# 指摘の種類ごとの件数（どんな直しがどれだけあるか）
vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4 --ignore=*/vendor/* --report=source /home/user/old-app

--report=source で「mysql_ 関数が 120 か所、each() が 15 か所」のように種類ごとにわかるので、作業の見積もりに便利です。

CSV に保存して、表計算ソフトで管理する

vendor/bin/phpcs --standard=PHPCompatibility --runtime-set testVersion 8.4 --ignore=*/vendor/* --basepath=/home/user/old-app --report=csv --report-file=phpcompat-result.csv /home/user/old-app

--basepath を付けると、ファイル名がフォルダからの相対パスになって読みやすくなります。CSV を Excel などで開けば、担当者や対応状況の列を足して、修正の管理表として使えます。

速くする

• --parallel=4：4 つ同時に調べる（PHP の PCNTL 拡張が必要なので、主に Linux・Mac で使える）
• --cache：結果を保存しておき、2 回目からは変わったファイルだけ調べる

設定をファイルにまとめる（phpcs.xml）

毎回長い指定を書くのは大変なので、設定をファイルにまとめておくと便利です。ツール用のフォルダに phpcs.xml を作ります。

<?xml version="1.0"?>
<ruleset name="old-app の互換性チェック">
    <description>PHP 8.4 へのバージョンアップで問題になる箇所を調べる</description>

    <!-- 調べるフォルダ -->
    <file>/home/user/old-app</file>

    <!-- 調べない場所 -->
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/cache/*</exclude-pattern>

    <!-- 調べるファイルの拡張子 -->
    <arg name="extensions" value="php,inc"/>

    <!-- 進み具合（p）とルールの名前（s）を表示する -->
    <arg value="ps"/>

    <!-- PHPCompatibility のルールで調べる -->
    <rule ref="PHPCompatibility"/>

    <!-- 動かしたい PHP のバージョン -->
    <config name="testVersion" value="8.4"/>
</ruleset>

このファイルがあるフォルダで、次のように打つだけで調べられます。

vendor/bin/phpcs

コマンドで --runtime-set testVersion 7.4 のように指定すると、ファイルの設定より優先されます。

指摘を除外する

直さなくていい指摘（たとえば、古い PHP と新しい PHP の両方で動くように、関数があるかを確かめてから使っている箇所）は、除外できます。まず -s で表示されるルールの名前（PHPCompatibility. で始まるもの）を確かめます。

その行だけ除外する

// 次の行の指摘を無視する（ルールの名前は例。-s の表示からコピーする）
// phpcs:ignore PHPCompatibility.FunctionUse.RemovedFunctions
$parts = split(',', $csv);

// 範囲をまとめて無視する
// phpcs:disable PHPCompatibility
require 'legacy/old-library.php';
// phpcs:enable PHPCompatibility

ルールごと除外する

<rule ref="PHPCompatibility">
    <!-- このルールの指摘は出さない（名前は例。-s の表示からコピーする） -->
    <exclude name="PHPCompatibility.FunctionUse.RemovedFunctions"/>
</rule>

除外しすぎると、直すべき箇所を見落とします。理由をコメントに書いて、最小限にしましょう。

WordPress や互換ライブラリを使っている場合

WordPress や、古い PHP に新しい関数を足すライブラリ（polyfill）を使っていると、「その関数は古い PHP には無い」という指摘が出ますが、実際には問題ありません。こうした誤った指摘を減らすための、追加のルール集が用意されています。

• PHPCompatibilityWP：WordPress 用
• PHPCompatibilityJoomla：Joomla 用
• PHPCompatibilityParagonie：random_compat・sodium_compat を使っている場合
• PHPCompatibilitySymfony：Symfony の polyfill を使っている場合

使い方は、--standard=PHPCompatibilityWP のように、PHPCompatibility の代わりに指定します。どれも testVersion は自分で指定する必要があります。

見つけられない問題もある

PHPCompatibility はコードを読むだけなので、動かしてみないとわからない変更は見つけられません。代表的なものです。

• PHP 8.0 の文字列と数値の比較：0 == "a" の結果が変わったが、書き方自体は正しいので指摘されない
• PHP 8.1 の、組み込み関数に null を渡すと非推奨：変数に null が入るかは、動かしてみないとわからない
• PHP 8.2 の動的プロパティ：どのプロパティに代入するかが実行時に決まる場合
• eval() や、変数に入れた名前で関数を呼ぶ書き方

公式も「すべての変更を見つけられるわけではない」としています。PHPCompatibility で ERROR を 0 にしたら、新しい PHP の検証環境で画面を一通り動かし、エラーログを確かめるところまでやりましょう。

おすすめの進め方

1. --report=source で全体の規模をつかむ（どんな直しが何か所あるか）
2. --report=csv で一覧を保存して、直す順番を決める
3. ERROR を直す。PHP 5 からなら、まず testVersion 7.4、次に 8.4 の 2 段階で
4. 新しい PHP の検証環境で動かす。エラーログを見ながら、PHPCompatibility で見つからない問題を直す
5. 余裕があれば WARNING（非推奨）も直す。次のバージョンアップが楽になる

まとめ

• PHPCompatibility は、PHP のバージョンアップで問題になる箇所を一覧にするツール。php7cc と違い、PHP 8 系の最新まで調べられる
• 新しい PHP（7.2 以上）で動かして、古いコードを読ませる。ツール専用のフォルダに入れると手軽
• testVersion で動かしたい PHP のバージョンを必ず指定する
• ERROR は必ず直す、WARNING は余裕があれば。--report=source・--report=csv で規模をつかんで管理する
• 動かさないとわからない変更は見つけられないので、検証環境での動作確認も必ず

参考

PHPCompatibility と PHP_CodeSniffer の公式の説明（2026 年 10 月 23 日時点）をもとにまとめています。

PHPCompatibility - GitHub

Usage - PHP_CodeSniffer Wiki