こんにちは！日々の開発、本当にお疲れ様です。
レガシーなPHPプロジェクトを引き継いだとき、こんな絶望感を味わったことはありませんか？
「このコントローラー、裏で一体どのクラスを呼び出しているんだ…？」
「ドキュメント？そんなもの、数年前から更新されていませんよ」
何万行もあるコードの海を前に、IDEの「参照を検索」機能だけで依存関係を追うのは、暗闇の中で糸電話の相手を探すようなものです。特に、マジックメソッドや動的なクラス名解決（`$class::factory()`のようなコード）が使われていると、静的解析ツールすら沈黙してしまいます。
ですが、安心してください。今回は、PHPの裏側を覗き見できる最強のデバッグ拡張機能「Xdebug」の関数トレース（Function Trace）を使い、コードの「隠れた依存関係」を完全に丸裸にして自動でグラフ化する、リバースエンジニアリングの極意をお伝えします。
これをマスターすれば、どんなにブラックボックス化したレガシーシステムでも、怖くありません。あなたの毎日のコードリーディングと設計把握が、劇的に楽になりますよ。
—
1. Xdebugの「関数トレース」とは何か？
多くの開発者は、Xdebugといえば「ブレークポイントを使ったステップ実行」を想像するでしょう。もちろんそれも強力ですが、実はXdebugには「PHPが実行したすべての関数呼び出しを、上から順にテキストファイルへすべて記録する機能（関数トレース）」が備わっています。
PHPのエンジン（Zend Engine）の内部で、どの関数がどの引数を伴って呼ばれ、どの順番でメモリ上にスタックされたのか。その全履歴が、まるで電車の運行記録（タイムライン）のように克明に出力されます。
Xdebugトレースデータのイメージ（実際はこのようなログが膨大に出力されます）
0.1234 123456 -> Controller->index() /var/www/html/app/Controller.php:45
0.1240 130000 -> Model->load(123) /var/www/html/app/Controller.php:48
0.1245 130500 -> Database->query(“SELECT FROM users…”) /var/www/html/app/Model.php:12
この膨大なログを人間の目で追うのは不可能ですが、「スクリプトで解析してクラス間の呼び出し関係（エッジ）を抽出し、MerdotやGraphvizで可視化」してしまえば、一瞬で「生きた設計図」が手に入ります。これが、今回目指すアプローチです。
—
2. 基礎セットアップ：Xdebugトレースを有効化する
まずは、Xdebugをインストールし、関数トレースを出力できるように設定しましょう。すでにXdebugが動いている環境でも、トレース用の設定を追加する必要があります。
お使いの `php.ini` または `xdebug.ini` に、以下の設定を記述してください。
[xdebug]
; Xdebugのモードとして「trace」を有効にする（step, debugなどとカンマ区切りで併用可能）
xdebug.mode = trace
; トレースファイルを出力するディレクトリを指定（書き込み権限に注意）
xdebug.output_dir = “/tmp/xdebug_traces”
; リクエストが来たら自動的にトレースを開始する（デバッグ用スクリプトの解析に便利）
xdebug.start_with_request = yes
; トレースファイルの命名規則（タイムスタンプを付与して一意にする）
xdebug.trace_output_name = “trace.%s-%r”
; 出力フォーマット（1を指定すると、人間が読みやすい構造化されたテキスト形式になる）
xdebug.trace_format = 1
設定を保存したら、WebサーバーまたはPHP-FPMを再起動し、正しく読み込まれているかを `php -v` や `phpinfo()` で確認してください。
—
3. 精度高い「HelloWorld」：小さなサンプルで動きを確認する
いきなり巨大なアプリケーションで試すとログが数ギガバイトになってしまうため、まずは小さな依存関係を持ったスクリプトで、トレースデータがどう生成され、どう可視化されるかを体験しましょう。
テスト用スクリプトの作成 (`index.php`)
以下の簡単なコードを用意します。`OrderService` が `Logger` と `Mailer` に依存しているシンプルな構造です。
logger = new Logger();
$this->mailer = new Mailer();
}
public function checkout() {
$this->logger->log(“Checkout started”);
$this->mailer->send(“customer@example.com”);
}
}
// 実行のエントリーポイント
$service = new OrderService();
$service->checkout();
このスクリプトをCLIで実行します。
php index.php
実行すると、指定した `/tmp/xdebug_traces` ディレクトリに `trace.xxxxxxxx.xt` というファイルが生成されます。中身を覗いてみると、PHPの内部関数やユーザー定義関数が実行された全履歴が記録されています。
—
4. トレースデータから「隠れた依存関係」を自動抽出する
ここからが本番です。生成されたテキストのトレースログを解析し、クラス間の呼び出し関係を抽出するPythonスクリプトを書いてみましょう。
以下のスクリプト（`parse_trace.py`）を用意します。このスクリプトは、トレース行から「どのクラスのメソッドから、どのクラスのメソッドが呼ばれたか」を検出し、Mermaid記法（クラス図・フロー図のテキスト表現）を自動生成します。
import re
import os
import glob
def parse_xdebug_trace():
# 最新のトレースファイルを自動取得
files = glob.glob(‘/tmp/xdebug_traces/trace..xt’)
if not files:
print(“トレースファイルが見つかりません。”)
return
latest_file = max(files, key=os.path.getctime)
print(f”解析対象ファイル: {latest_file}”)
edges = set()
current_class = “Global”
# Xdebugのトレースフォーマット（format=1）をパースする正規表現
# 例: 4 0.0003 393688 -> OrderService->__construct() /path/to/index.php:14
call_pattern = re.compile(r’->\s+([a-zA-Z0-9_]+)::([a-zA-Z0-9_]+)\(‘)
with open(latest_file, ‘r’, encoding=’utf-8′, errors=’ignore’) as f:
for line in f:
match = call_pattern.search(line)
if match:
called_class = match.group(1)
# 簡易的に「呼び出し元から呼び出し先へのエッジ」を記録
# 実務ではコールスタック（呼び出し階層）を正しく追跡するとさらに精度が上がります
if current_class != called_class:
edges.add((current_class, called_class))
current_class = called_class
# Mermaid形式で出力
print(“\n— 自動生成された依存関係 (Mermaid) —“)
print(“graph TD;”)
for caller, callee in edges:
print(f” {caller} –> {callee};”)
if __name__ == “__main__”:
parse_xdebug_trace()
このPythonスクリプトを実行してみます。
python3 parse_trace.py
実行結果（出力されるMermaidコード）
— 自動生成された依存関係 (Mermaid) —
graph TD;
Global –> OrderService;
OrderService –> Logger;
OrderService –> Mailer;
おぉ、どうでしょう！静的なコード解析ではなく、「実際にコードを動かした実績ベース」で、`Global` から `OrderService` が呼ばれ、その中で `Logger` と `Mailer` が使われているという隠れた依存関係が、綺麗にグラフ化のためのコードとして抽出されました。
このMermaidのコードを、GitHubのMarkdownや、Notion、あるいは [Mermaid Live Editor](https://mermaid.live/) に貼り付けるだけで、一瞬で美しいクラス依存関係図が描き出されます。
—
5. 実務でこの手法をスケールさせるための知見
「小さなスクリプトで動くのは分かったけれど、実際の数万行あるフレームワーク（LaravelやSymfonyなど）では、フレームワーク自体の内部処理（コアライブラリ）が混ざってグラフが巨大化するのでは？」
その通りです。実務のアプリケーションでこの手法を適用する際には、以下の「エンジニアの知見」を取り入れることで、ノイズを排除し、真に知りたい業務ロジックの依存関係だけを浮かび上がらせることができます。
1. ベンダープレフィックスの除外
解析スクリプト側で、`Illuminate\`, `Symfony\`, `Composer\` などのフレームワーク固有のネームスペースやベンダー製ライブラリをホワイトリスト・ブラックリスト方式でフィルタリングします。これにより、自社製ドメインモデル間の依存関係だけをクリーンに抽出できます。
2. 特定のユースケース（機能単位）でトレースを絞る
「ログイン処理」「注文確定処理」など、テストしたい特定の機能（エンドポイント）に絞ってリクエストを送り、その瞬間のトレースだけを取得します。これにより、アプリケーション全体のスパゲッティのような図ではなく、「その機能専用のミニ設計図」が手に入ります。
3. 動的ディスパッチの可視化
DIコンテナやサービスlocatorを介して動的にインスタンス化されるコードは、IDEの静的解析では追えませんが、Xdebugのトレースなら「実際にどの具象クラスがインスタンス化されたか」が100%の確度で記録されます。これが最大のメリットです。
—
まとめ
レガシーコードの海に立ち向かうとき、私たちは往々にして「コードを読む」というアプローチだけで何とかしようとしがちです。しかし、時には「コードに動いてもらい、その足跡を記録（トレース）して、後から地図を起こす」というリバースエンジニアリングの発想が、絶望的な状況を打破するカギになります。
Xdebugの関数トレースと簡単なパース処理を組み合わせるこの手法は、ドキュメントのないプロジェクトのオンボーディング時間を何分の一にも短縮してくれます。
「これをマスターすれば、どんなレガシーシステムが来ても怖くない」――そう確信できた瞬間から、あなたのエンジニアとしての視野は一段と広がります。ぜひ、次のプロジェクトのコード解析にこっそり導入してみてください。あなたの開発ライフが、驚くほど快適になりますように！