レガシーPHPの「絶望」を打破する：Xdebug関数トレース×WebSequenceDiagramsによる自動シーケンス図生成
テックリードの仕事とは、綺麗なコードを書くことだけではない。むしろ、ドキュメントが完全に腐敗し、誰も全貌を把握していない「数年前の巨大レガシーモノリス」に新機能を安全に実装し、チーム全体の開発生産性を死守することこそが、真の腕の見せ所だ。
「このコントローラー、どこからどのモデルを呼び出して、どのトランザクションを張っているんだ……？」
IDEの「定義へジャンプ」を何度往復しても、ポリモーフィズムや動的メソッド呼び出しの海に溺れ、脳内でコールスタックが爆発した経験はないだろうか。
今回は、Xdebugが吐き出す生々しい関数トレース（Function Trace）をパースし、WebSequenceDiagrams（またはPlantUML）と連携させて、複雑怪奇なオブジェクト間のインタラクションを完全自動でシーケンス図化するワークフローを解説する。
ネットを検索すれば転がっている「Xdebugのインストール方法」や「`xdebug.mode=debug`の書き方」などという初歩的な解説は一切しない。プロの現場で即座にROI（投資対効果）を最大化するための、実践的な自動化パイプラインを構築しよう。
—
なぜ「ステップ実行」だけではレガシーコードに太刀打ちできないのか？
ブレークポイントを張り、ステップオーバーやステップインを繰り返すデバッグ手法は、バグの局所特定には最強だ。しかし、「コード全体の処理フローの全体像を把握する」という目的においては、実は極めて効率が悪い。
- コンテキストの喪失: デバッグに夢中になるあまり、「今、全体フローのどのレイヤーにいるのか」を見失う。
- 非同期・イベント駆動の隠蔽: フレームワークの内部イベントやミドルウェアを挟んだ処理は、ステップ実行で追うと無限の迷宮に迷い込む。
ここでXdebugの関数トレース（Function Trace）の出番となる。これは、PHPの実行プロセスが辿ったすべての関数・メソッドの呼び出し、引数、メモリ消費量、実行時間を時系列でテキストファイルに全記録する機能だ。
しかし、出力されるのは数万行におよぶ生テキストのログである。人間が肉眼で読めるものではない。だからこそ、「テキストをパースし、UMLのシーケンス図に変換する」というパイプラインを開発環境に組み込む必要があるのだ。
—
実践ワークフロー：トレース出力からシーケンス図生成まで
このワークフローの全体像は以下の通りだ。
1. 特定リクエストのトレース有効化: 開発環境（Docker等）で、特定のクエリパラメータやヘッダーが付いたリクエストだけXdebugのトレースを発動させる。
2. トレースログの生成: `XDEBUG_TRACE`ファイルが出力される。
3. パーサーによるUML（PlantUML / WebSequenceDiagrams形式）への変換: 生ログから不要な内部関数（`strlen`やフレームワークのコアライブラリ等）をフィルタリングし、アプリケーション独自のクラス間呼び出しのみを抽出し、シーケンス図のDSLに変換する。
4. 図のレンダリング: ブラウザやIDE上で視覚化する。
1. 爆速でトレースを有効化する `php.ini` 設定
開発コンテナ全体でトレースを常時ONにすると、I/Oの負荷でアプリケーションが死ぬ。必ず「必要な瞬間だけ、特定のトリガーで発動させる」設定にすること。
[xdebug]
; プロファイラとトレースモードを有効化
xdebug.mode = trace
; トリガー方式を「get/postリクエストパラメータ」に指定
xdebug.start_with_request = trigger
; トリガー名を設定（例: ?XDEBUG_TRACE=1 で発動）
xdebug.trace_trigger = XDEBUG_TRACE
; トレースファイルの出力先ディレクトリ
xdebug.trace_output_dir = “/var/www/html/storage/traces”
; 出力フォーマットを人間が解析しやすい「セカンド（秒単位の実行時間・メモリ含む）」に設定
xdebug.collect_output = 0
xdebug.collect_parameters = 1
xdebug.collect_return = 1
これで、ブラウザや `cURL` から `http://localhost/api/v1/orders?XDEBUG_TRACE=1` にアクセスするだけで、指定ディレクトリに数メガバイトの `.xt` ファイルが生成される。
—
自動化の要：トレースログをシーケンス図へ変換するカスタムスクリプト
Xdebugのトレースログ（`.xt`）は、以下のようなタブ区切りのフォーマットで出力される。
Version: 3.2.0
File format: 4
0.1234 123456 -> {main}() /var/www/html/public/index.php:0
0.1235 123500 -> App\Http\Controllers\OrderController->__construct() /var/www/html/app/Http/Controllers/OrderController.php:25
0.1238 124000 -> App\Services\OrderService->process() /var/www/html/app/Services/OrderService.php:42
このテキストを読み込み、クラス間のメッセージパッシングを抽出して、WebSequenceDiagramsやPlantUMLの構文に変換するCLIスクリプト（Python製）をプロジェクトの `tools/` 配下に常備しよう。
`tools/trace_to_sequence.py`
!/usr/bin/env python3
import re
import sys
from pathlib import Path
def parse_xdebug_trace(file_path):
“””
Xdebugの関数トレースファイル（.xt）をパースし、
オブジェクト間の呼び出し関係（シーケンス）を抽出する
“””
call_stack = []
interactions = []
# ログ行の正規表現パターン（関数呼び出し・メソッド呼び出しをキャッチ）
# 例: 0.1238 124000 -> App\Services\OrderService->process() file:line
pattern = re.compile(
r’^\s[\d\.]+\s+\d+\s+([->]+)\s+([a-zA-Z0-9_\-\\]+)(?:->|::)([a-zA-Z0-9_]+)\s\((.?)\)’
)
with open(file_path, ‘r’, encoding=’utf-8′, errors=’ignore’) as f:
for line in f:
match = pattern.search(line)
if match:
direction, class_name, method_name, params = match.groups()
# フレームワークのコアやvendor配下をノイズとして除外するフィルター
if “Illuminate\\” in class_name or “Symfony\\” in class_name or “Vendor\\” in class_name:
continue
if direction == ‘->’:
if call_stack:
caller = call_stack[-1]
callee = class_name
if caller != callee:
interactions.append((caller, callee, method_name))
call_stack.append(class_name)
elif direction == ‘<-':
if call_stack:
call_stack.pop()
return interactions
def generate_plantuml(interactions):
"""抽出したインタラクションからPlantUML形式のテキストを生成する"""
uml = ["@startuml", "autonumber", "skinparam BoxPadding 10", "skinparam ParticipantPadding 10"]
# 登場するクラスの重複を排除して定義
participants = set()
for caller, callee, _ in interactions:
participants.add(caller)
participants.add(callee)
for p in sorted(participants):
uml.append(f"participant \"{p}\" as {p.replace('\\', '_')}")
uml.append("")
# 呼び出しフローを追加
for caller, callee, method in interactions:
c_id = caller.replace('\\', '_')
e_id = callee.replace('\\', '_')
uml.append(f"{c_id} -> {e_id}: {method}()”)
uml.append(“@enduml”)
return “\n”.join(uml)
if __name__ == “__main__”:
if len(sys.argv) < 2:
print("Usage: python trace_to_sequence.py
sys.exit(1)
xt_file = Path(sys.argv[1])
if not xt_file.exists():
print(f”Error: File {xt_file} not found.”)
sys.exit(1)
interactions = parse_xdebug_trace(xt_file)
plantuml_text = generate_plantuml(interactions)
# 出力ファイル名
output_file = xt_file.with_suffix(‘.puml’)
with open(output_file, ‘w’, encoding=’utf-8′) as out:
out.write(plantuml_text)
print(f”Success! PlantUML generated: {output_file}”)
このスクリプトを実行することで、数万行のログが、一瞬で数行の洗練されたPlantUMLコードに変換される。
python3 tools/trace_to_sequence.py storage/traces/trace.12345.xt
出力: storage/traces/trace.12345.puml
生成された `.puml` を、IntelliJ/PhpStorm の「PlantUML Integration」プラグインや、VS Codeの「PlantUML」拡張機能でプレビューすれば、美しいシーケンス図が目の前に立ち現れる。
—
チーム開発でこのワークフローを定着させるための共有化ルール
属人化しがちなレガシーコード解析をチームの共通資産にするために、以下のルールと設定をプロジェクト（Gitリポジトリ）に組み込む。
1. `.env.example` への明示的な追記
開発メンバー全員が同じ設定でトレースを有効化できるよう、環境変数テンプレートにXdebugのトリガー設定をドキュメント化する。
==========================================
Xdebug Trace & Sequence Diagram Settings
==========================================
デバッグ時のトレース有効化トリガー名
XDEBUG_TRIGGER=XDEBUG_TRACE
トレース出力先のコンテナ内パス
XDEBUG_TRACE_DIR=/var/www/html/storage/traces
2. チーム共有タスクランナー（Makefile）の整備
「どのコマンドを打てば図が出るのか」を忘れないように、Makefileのレシピとしてコード化する。開発者はワンコマンドでレガシーコードの可視化を行えるようになる。
.PHONY: trace-clean trace-parse
古いトレースログの一括削除
trace-clean:
@rm -f storage/traces/.xt storage/traces/.puml
@echo “🧹 Trace logs cleaned.”
最新のトレースログを検出してPlantUMLに変換
trace-parse:
@latest_xt=$$(ls -t storage/traces/.xt 2>/dev/null | head -n 1); \
if [ -z “$$latest_xt” ]; then \
echo “❌ No trace file found in storage/traces/. Send request with ?XDEBUG_TRACE=1”; \
exit 1; \
fi; \
python3 tools/trace_to_sequence.py “$$latest_xt”; \
echo “✨ Successfully converted to PlantUML: $${latest_xt%.xt}.puml”
日々の開発フローはこうだ：
1. ブラウザから問題のエンドポイントに `?XDEBUG_TRACE=1` をつけてアクセス。
2. ターミナルで `make trace-parse` を実行。
3. エディタを開いて、瞬時に生成されたシーケンス図を確認しながらコードの該当箇所を修正する。
—
テックリードが知るべき「プロの隠し技」と注意点
最後に、この手法を実務で運用する上で絶対に押さえておくべき知見を共有する。
- 循環呼び出しと再帰の制御:
レガシーコードには、ORMの遅延ローディングやイベントリスナーの連鎖によって、無限ループや莫大な再帰呼び出しが含まれていることが多い。パーサー側（Pythonスクリプト）で同一パスの連続呼び出しをサニタイズ（間引き）するロジックを入れておかないと、シーケンス図が縦に無限に伸びて視認性が死ぬ。上記のサンプルコードでは `caller != callee` による最低限のフィルタリングを入れているが、必要に応じて深さ制限（Max Depth）を設けるとさらに実用的になる。
- 本番環境での絶対的禁止:
口酸っぱく言うまでもないが、`xdebug.mode=trace` は本番環境（Production）では絶対に有効化してはならない。ディスクI/Oの枯渇およびパフォーマンスの壊滅的な低下を引き起こす。開発（Development）またはステージング（Staging）の限られたネットワーク内でのみ使用すること。
結び：ドキュメントなきコードへの恐れをなくせ
「ドキュメントがないから直せない」は、プロの開発チームにとって言い訳にならない。
コードこそが唯一にして最大の真実であるならば、コードから動的にドキュメント（図）を生成するパイプラインを自らの手で構築すればいい。
Xdebugの関数トレースとシーケンス図の自動化は、レガシーコードという名のブラックボックスに強烈な光を当て、チームの認知負荷を劇的に軽減する強力な武器となる。明日の朝、あなたのプロジェクトの最も難解なコントローラーで、ぜひこのワークフローを試してみてほしい。その瞬間から、コードを読み解くスピードが次元を変えて加速するはずだ。