VSCode でワードプレスデバッグ環境を構築する

このページでは、VSCode でワードプレス（テーマなど）のデバッグを行う環境構築方法の解説を行います。

これにより VSCode で下記のようなことを行うことが可能になります。

プログラムを途中で止めることができる
止めた瞬間の変数の中身が確認できる
関数やファイルの呼び出し元がすぐに確認できる

実際にワードプレスのテーマ開発やテーマのカスタマイズを行なっていると、うまく動いてくれなくて困ることが多いですが、このデバッグの機能を利用することで、大体すぐに解決できてしまいます。

そんなデバッグ環境を VSCode に導入する手順をこのページでは解説していきます。

VSCode をまだインストールしていない、MAMP やワードプレスをインストールしていない、という方は下記ページを参考にして事前にインストールを行っておいてください。

Visual Studio Code でワードプレス開発環境を構築する（MacOSX）

Contents

Xdebug の有効化
PHP Debug プラグインのインストール
- PHP Debug プラグインの追加
- launch.json の作成
launch.json の設定
デバッグの実行
まとめ

Xdebug の有効化

VSCode にデバッグ環境を構築するためには、まずは Xdebug の有効化を行う必要があります。

Xdebug は、上記で示した PHP のデバッグ機能を提供するソフトウェアです。

この Xdebug の有効化については下記で解説していますので、こちらを参考にしていただければと思います。

Eclipse にデバッガー（Xdebug）を導入

Eclipse 向けの解説になりますが、Xdebug の有効化の部分の解説については VSCode でも同じです。

具体的に上記ページで実施していただきたいのは「デバッガー（Xdebug）の有効化」と「Xdebug 有効化の確認」です。

これにより Xdebug が有効化され、Xdebug を起動させて PHP のデバッグを行えるようになります。

続いては、この Xdebug を VSCode 上で動作させる様にする手順を解説していきます。

PHP Debug プラグインのインストール

VScode 上で Xdebug を動作させるためには、PHP Debug プラグインをインストールし、有効化する必要があります。

PHP Debug プラグインの追加

VSCode を起動し、画面左側の下記のマークをクリックし、上側のテキスト入力フィールドに「PHP Debug」と入力します。

検索結果が表示され、その中に「PHP Debug」があるはずです。

この「PHP Debug」の Install ボタンをクリックします。これだけで「PHP Debug」のインストールと有効化が完了します。

launch.json の作成

この PHP Debug のインストールにより、メニューバーから「デバッグ」→「構成を開く」をクリックし、PHP が選択できる様になります。

PHP をクリックすると、自動的にワークスペース直下に .vscode というフォルダが作成され、

その中に “launch.json” というファイルが作成されます。このファイルがデバッグの設定を行うファイルになります。

launch.json の設定

デバッグの設定は “launch.json” を変更することで設定することが可能です。

まずは launch.json の中身を見てみましょう。おそらく下記の様になっていると思います（コメントは略しています）。

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

この launch.json には２つのデバッグの構成が定義されています。

Listen for Xdebug：１つ目が "name": "Listen for XDebug" の構成で、Xdebug を利用してウェブアプリをデバッグするためのもの
ワードプレス開発時に使うのはこっち
Launch currently open script：２つ目の "name": "Launch currently open script" は開いている PHP ファイルを単体でデバッグするための構成

上述の通りワードプレスの開発・デバッグで使用するのは Listen for Xdebug なので、こちらの設定や動作させ方を中心に解説していきます。

で、Listen for Xdebug の設定は下記の場合はこのままで良いはずです。

PHP の設定：php.ini で「xdebug.remote_port」の値を 9000 に設定している
ワークスペースの設定：ワークスペースをワードプレスインストールフォルダ直下から作成している
（ワークスペース直下に wp-blog-header.php や index.php がある）

もしこれらを変更している場合は下記の部分を変更します。

PHP の設定を変更している場合：Listen for Xdebug の “port” の設定を「xdebug.remote_port」で設定した値に変更する
ワークスペースを変更している場合：Listen for Xdebug の “pathMappings” の設定を追加し、ワードプレスインストールフォルダを指定する

例えば「xdebug.remote_port」を “9001” に設定し、ワークスペースをワードプレスインストールフォルダ直下にしていない場合は、下記の様に launch.json を変更すれば良いです（ワードプレスを /Applications/MAMP/htdocs にインストールしている場合の例です）。

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "pathMappings": {
                "/Applications/MAMP/htdocs": "/Applications/MAMP/htdocs"
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

デバッグの実行

ここまでで一通り必要なソフトウェアのインストールや有効化・設定が完了し、デバッグが行える環境が構築できたことになります。

ということで、実際にデバッグを実行していきましょう！

ブレークポイントの設定

まずはブレークポイントの設定を行います。ブレークポイントとはデバッグ中にプログラムを停止させるポイントになります。

ブレークポイントは PHP プログラムの左側をクリックして赤丸（●）を付けることで設定することができます。

これにより、デバッグを行うと赤丸（●）の PHP プログラムが実行される直前でプログラムが停止するようになります。

デバッグの動作確認を行うために、実際にブレークポイントを設定してみましょう！

まずはワードプレスでページ表示する際に必ず通過する場所にブレークポイントを設定しておきましょう。下記ファイルの

{ワードプレスインストールフォルダ}/wp-blog-header.php

下記プログラムの左側にブレークポイントを設定してみてください。

wp();

プログラムの左側に赤丸（●）が付けば成功です！

デバッグの開始

続いてデバッグの開始を行います。

デバッグを開始する前に、まずはデバッグの構成の選択を行います。

画面左側の虫マークをクリックすると、

デバッグの構成管理画面が表示されます。

さらに画面上側にあるセレクトボックスをクリックすると、

launch.json で設定されているデバッグの構成の名前が表示されるはずです。

ここで、「Listen for Xdebug」を選択することで、ワードプレスのデバッグが行える様になります。

次にデバッグの開始を行います。メニューバーから「実行」→「デバッグの開始」をクリックするだけでデバッグの開始を行うことができます。

デバッグの構成を「Listen for Xdebug」に設定している場合、デバッグの開始を行ってもプログラムが動き出すわけではありません。

デバッグの開始を行うことで、VSCode は下記のような状態になります。

Xdebug 起動中に、ブレークポイントが設定されたプログラムが実行されるのを監視

ですので、デバッグの開始を行なった後に、Xdebug を起動し、さらにウェブブラウザからページ表示を行えば、ワードプレスが起動してプログラムが実行され、ブレークポイント通過時に自動的にプログラムを停止させてくれます。

プログラムと Xdebug の起動

いよいよプログラムを起動させ、ブレークポイントでプログラムを停止させます。

ワードプレスの場合、ウェブブラウザからワードプレスが生成するページを表示するだけでプログラムが自動的に起動します。

で、ここでポイントになるのが Xdebug を起動させることです。

Xdebug はウェブブラウザの URL 欄に、URL + ?XDEBUG_SESSION_START を指定することで、そのページを Xdebug を起動させた状態で表示させることができます。

ですので、例えばデバッグ対象のワードプレスのトップページの URL（＋ポート番号）が「http://localhost:888」の場合、下記のようにウェブブラウザの URL に指定することで、Xdebug を起動した状態でページ表示を行うことができます。

http://localhost:8888?XDEBUG_SESSION_START

つまり、上記のような URL をウェブブラウザに指定すれば、Xdebug を起動させた状態でページ表示のためのプログラムが実行され、ブレークポイントを通過する際にプログラムを停止してくれます。

Xdebug 起動の自動化

毎回 ?XDEBUG_SESSION_START を指定するのも面倒だと思います

そんな場合は php.ini に下記を追記することをオススメします

xdebug.remote_autostart=1

これにより ?XDEBUG_SESSION_START を指定しなくても Xdebug が自動的に起動するようになります

早速上記のように URL を指定してデバッグをしてみましょう！うまくいけば、先ほどブレークポイントを設定した下記の場所でプログラムが停止されるはずです。

デバッグの仕方

最後に簡単にデバッグの仕方や画面の見方を解説しておきます。

デバッグの情報を確認する

まず画面の左側にはデバッグの情報が表示されています。

変数ウィンドウにはプログラム停止時点の各変数の内容が表示されています。プログラムが上手く動かない時などに、変数の内容がどのように変化するかを確認しながらデバッグするのに便利です。

コールスタックウィンドウには、プログラムが停止するまでに呼び出された関数や読み込みされたファイルの履歴が表示されています。

プログラムを操作する

また、停止させたプログラムは、下記の６つのボタンから操作することができます。

続行ボタン（一番左のボタン）では、次のブレークポイントまでプログラムを進めることができます。ブレークポイントが他にない場合はプログラムは最後まで実行されます。

ステップオーバーボタン（左から二番目のボタン）では、プログラムを次の行まで進めることができます。

ステップインボタン（左から三番目のボタン）でも、プログラムを次の行まで進めることができます。

ステップオーバーボタンとステップインボタンとの違いは、停止している行が関数呼び出しやファイル読み込みの際に、ボタンクリック時にその関数やファイルに入り込むかどうかです。

例えば先ほど wp(); の直前でプログラムを停止させましたが、ステップインボタンをクリックすると、 wp 関数の中に入り込み、wp 関数の最初の行でプログラムが停止することになります。

ステップオーバーボタンをクリックした場合は、wp 関数には入り込まず、次の行の require_once の行にプログラムが進みます。

ステップアウトボタン（左から四番目のボタン）では、プログラムを関数終了直後まで進めることができます。

再起動ボタン（左から五番目のボタン）では、プログラムを最初から再起動することができます（あまり使ったことないです）。

停止ボタン（一番右側のボタン）では、デバッグを停止させることができます。

これらのボタンを駆使して、上手く動作しないプログラムの動きを追うことでその原因を解析し、修正することでデバッグをしていくことになります。

まとめ

このページでは、VSCode にデバッグ環境を構築する方法について解説しました。

テーマ等の開発やカスタマイズを行う上では、このデバッグ環境はめちゃめちゃ便利です。もちろん自身が開発・カスタマイズする部分のデバッグを行う上でも便利ですが、ステップ実行等を行うことでワードプレス本体の動きを理解することもできます。

Xdebug を有効化したり、PHP Debug をインストールしたりと色々大変ですが、その苦労を上回るメリットがあると思いますので、是非このページを参考にしてデバッグ環境の構築を行ってみてください！