WordPressのデバッグ
WordPressのテーマやプラグインの様なPHPで書かれたコードをデバッグするには、var_dumpという関数を使用するらしいのですが、私はWindowsのアプリ開発が長かったので「ソースレベルデバッグ」と呼ばれる手法の方がなじみがあります。
これはVisual Studio等の開発環境でソースコードに「ブレークポイント」と呼ばれるマークを設定しておくと、プログラムがその地点に到達した時に一時停止します。その時のローカル変数やグローバル変数の値等を参照しながらデバッグする手法となります。(下の画像はVisual Studioの画面になっています。)
PHPでも「XDebug」という機能を使用すると、Visual Studio Code(VSCode)で同じようなデバッグができる様なので設定してみます。PHPの実行環境はWSL2(Ubuntu 24.04LTS)を使用しています。サーバーの設定変更が可能であれば、他のサーバー環境でも動作すると思われます。
今回は画像が多いです。(記事を読むには30分程度かかるかもしれません。)
WSL２(Ubuntu)を設定します
すでにWordpressが実行できる状態のWSL2を前提にご説明いたします。WSL2にWordpressをインストールするには、お手数ですが過去の記事等をご覧ください。また、Linux上の設定ファイル等も変更するので、同記事内で紹介しているWinSCP等もご活用ください。
まずWSL2(Ubuntu)上に「XDebug」と呼ばれるパッケージをインストールします。(以降の作業はルート権限で実行しています。)
apt install php-xdebugXDebugパッケージの設定ファイル「/etc/php/8.3/mods-available/xdebug.ini」を以下の様に修正します。設定ファイル内の「xdebug.so」ファイルの場所とIPアドレスは環境によって違うかもしれませんので、以降の方法で確認してください。
[xdebug]
zend_extension=/usr/lib/php/20230831/xdebug.so
xdebug.mode = debug,develop,trace
xdebug.start_with_request = yes
xdebug.client_port = 9003ターミナル画面で「find /usr -type f -name xdebug.so」と入力すると、ファイルの場所が表示されます。
root@DESKTOP-CQEA49P:/var/www/html# find /usr -type f -name xdebug.so
/usr/lib/php/20230831/xdebug.so
root@DESKTOP-CQEA49P:/var/www/html#次に「/etc/ssh/sshd_config」を修正します。34行目辺りに以下の文字列を追加して保存します。
(※以下の設定を行うとルート権限でSSHにログインできてしまうため、ローカル環境で実行するには問題はないのですが、公開しているサイトで行う場合はセキュリティ上の不安があるので、公開鍵認証方式のログイン方法などを併用してください。今回は開発(ソースコードの修正)も行える様にするためにこの設定にしました。デバッグのみ(見るだけ)であればこの修正は必要ありません。)
PermitRootLogin yesSSHを有効化して再起動します。
systemctl enable ssh
systemctl restart sshVSCodeと拡張機能をインストールします
Windowsの検索で「visual studio code」と入力して、表示された画面からVSCodeをインストールします。
検索欄に「visual studio code」などと入力してVSCodeアプリを検索して起動します。起動直後は英語なので、まず日本語化します。左側の「Extention」ボタンを押して、表示されたテキストボックスに「japanese」などと入力して、最初に表示されたMicrosoftの日本語化パッケージの「Install」ボタンを押します。表示された「Change Language and Restart」ボタンを押すと再起動します。
再起動後に「WSL拡張をインストールしますか」と表示されます。今回は使用しませんが何度も表示されるので一応インストールしておきます。
左側の「機能拡張」ボタンを押して、表示されたテキストボックスに「remote ssh」と入力して、最初に表示されたMicrosoftの「Remote – SSH」パッケージの「インストール」ボタンを押します。
次に検索欄に「php debug」と入力して提供元が「Xdebug」になっている拡張機能をインストールします。
ホスト(WSL2)との接続設定を行います
VSCodeの左下にある青いボタンを押して、上部の検索ウィンドウからRemote SSHの「Connect Current Window to Host…」を選択します。何回か試行した場合は、「現在のウィンドウをホストに接続する…」という日本語表示になっているかもしれません。
「SSHホストを構成する」を選択します。
「C:\Users\<ユーザー名>\.ssh\config」を選択します。
設定画面が開くので以下の様に修正します。ホスト(WSL2)のIPアドレスはご自身の環境にあわせて修正してください。(ルート権限でログインしない場合は ‘root’ の部分をユーザー名(user01等)に変更してください。以降「ルート(root)」の部分を「ユーザー(user01等)」に読み替えてください。)
Host root-172.19.88.145
HostName 172.19.88.145
User root
ForwardAgent yes
再度左下にある青いボタンを押して、上部の検索ウィンドウからRemote SSHの「Connect Current Window to Host…」を選択します。
上部に表示された検索欄から「root-172.19.88.145」を選択します。
OSを選択するオプションで、「Linux」を選択します。
パスワード入力を要求されるので、WSL2のルートのパスワードを入力してenterキーを押します。
接続が成功すると、以下の様な画面になります。左下にホスト名が表示されています。
もし以下の様なエラーが表示された場合は、以降の項目をチェックしてみてください。
「C:\Users\<ユーザー名>\.ssh」フォルダ内にある「known_hosts」ファイルを開きます。以下の様なWSL2のIPアドレスから始まる行をすべて削除してから再度接続します。
172.19.88.145 ssh-ed25519 ...
172.19.88.145 ssh-rsa ...
172.19.88.145 ecdsa-sha2-nistp256 ...ブレークポイントを設定して動作確認をします
左上にある「エクスプローラー」ボタンを押して、表示された画面から「フォルダーを開く」ボタンを押します。
上部の検索欄から、Wordpressがインストールされている場所(/var/www/html あたり)を選択して「OK」ボタンを押します。
WSL2のパスワードを入力します。
以下の様な画面が表示されたら、「はい、作成者を信頼します」ボタンを押します。
再度「拡張機能」ボタンを押して、ホスト(WSL2)側にも「PHP Debug」プラグインをインストールします。この作業によって、ホスト側のPHPソースコードにブレークポイントが設定できる様になります。
調査したいソースコードを開いて、コードの行番号の少し左側をクリックするとブレークポイントが設定できます。もう一度クリックすると解除されます。「F9」キーでも設定／解除が可能です。また、行番号の上で右クリックすると、停止する条件付きのブレークポイントも設定できるメニューが表示されます。
左側の「実行とデバッグ」ボタンを押します。以下の様な画面が表示された場合は、「launch.jsonファイルを作成します」をクリックします。
左側の「実行とデバッグ」ボタンを押して表示された画面で「Listen for Xdebug」が選択されているのを確認して、表示された画面の「実行とデバッグ」ボタンを押すとデバッグが開始されます。
ブラウザでWordpressのローカルサイトを表示させて、何かサイト内の他のページに移動させるとブレークポイントで停止します。停止しない場合はキャッシュされていると思われますので、他の画面を表示させてみてください。(WordPressにログインした状態で操作したほうが停止しやすい様です。)
Chromeをお使いであれば、ページの右クリックの「検証」メニューで検証ツールを起動して、上部の「ネットワーク」タブで表示された画面にある、「キャッシュを無効化」チェックボックスで一時的にキャッシュを無効化しておくといいかもしれません。
それでも停止しない場合は、「実行とデバッグ」画面の設定ボタンを押して表示された設定(オレンジで囲まれた部分)が同じようになっているかご確認ください。(“hostname”項目は無くても動作する様です。)
設定ファイル内容 (クリックすると開きます。)
{
// IntelliSense を使用して利用可能な属性を学べます。
// 既存の属性の説明をホバーして表示します。
// 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"hostname": "172.19.88.145"
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9003,
"runtimeArgs": [
"-dxdebug.start_with_request=yes"
],
"env": {
"XDEBUG_MODE": "debug,develop",
"XDEBUG_CONFIG": "client_port=${port}"
}
},
{
"name": "Launch Built-in web server",
"type": "php",
"request": "launch",
"runtimeArgs": [
"-dxdebug.mode=debug",
"-dxdebug.start_with_request=yes",
"-S",
"localhost:0"
],
"program": "",
"cwd": "${workspaceRoot}",
"port": 9003,
"serverReadyAction": {
"pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
"uriFormat": "http://localhost:%s",
"action": "openExternally"
}
}
]
}ブレークポイントにヒットした場合は、左側にローカル変数や呼び出し履歴等の情報が表示されます。画面上部にあるツールボタンを使用すると、ステップオーバー(現在の関数を実行して次の行に移動します。)やステップイン(呼び出す関数内に移動します。)などの機能が使用できます。デバッグ処理の停止もこのツールバーから行います。各機能の詳細はこちらのリンク等をご覧ください。(リンク先はJavaScriptの例ですがデバッガ(ツールボタン)の使用方法はほぼ同じと思われます。)
接続を切断するには、左下のホストのIPアドレスが表示されている部分をクリックします。上部のメニューにある「リモート接続を終了する」を選択するとホストと切断されます。
その他
PHPのデバッグをXDebugで行うために、ホストとローカルに同じソースファイルを用意するパターンが多い様ですが、今回の方法だと、ホスト(WSL2)にあるソースファイルだけで開発とデバッグが行えます。ファイルが分散しないのでソース管理も楽かもしれません。
おまけで「PHP Intelephense」というプラグインを入れておくと、ソースファイルの解析が楽になります。
このプラグインをインストールすると、関数の定義箇所へ移動したり、体裁を整えたりする機能がマウスの右クリックメニューに表示されるようになります。その他、コードの補完機能など色々な編集機能が付いている様です。
非常に便利なプラグインですが、インストールした場合は誤動作を防ぐため、VSCodeに組み込みのPHPの言語機能をオフにしておいた方がいい様です。プラグインの検索欄に「@builtin php」と入力して、表示された「PHP Language Features」の「無効にする」ボタンでオフにできます。
以上です。よろしかったらお試しください。
