WordPress開発者なら必ず知っておきたいXdebugの使い方

開発者なら誰でも経験することですが、コードの記述に修正とやり直しは付きものです。開発プロセスにはデバッグが欠かせず、動作の疑わしいコードには何度も手を加えていく必要があります。

コードのバグを取り除くのに有用なのが、PHPのXdebug拡張モジュールです。

Xdebugのすばらしい点のひとつは、その柔軟性です。好みのフレームワークや開発環境に関係なく、自分のワークフローに合ったXdebugのバージョンを見つけることができます。Xdebugを使いこなすのにそれほど時間はかからないでしょう。

今回の記事では、Xdebugのインストール方法、セットアップへの組み込み、そして一般的な使用方法について詳しくご紹介します。

まず、Xdebugとは何なのか、どんな役割を果たすのか見てみましょう。

Xdebugとは

Xdebugは、PHPコードのデバッグに使える人気の拡張モジュールです。選択した環境からインストールし、ステップデバッガとして利用できます。

要するに、コードを一行ずつ処理することが可能になり、コードがプログラム内でどのように動作し、相互作用するか、またその出力について詳しく調査できるようになります。その情報に基づいて、適宜変更を加えることが可能です。

しかし、Xdebugではもっと多くのことができます。

• 一連のメトリクスと可視化機能を使い、コードのパフォーマンスを分析することができる
• PHPの単体テスト実行時に、コードの部位を確認できる
• Xdebugにはトレース機能があり、すべての関数コールをディスクに書き出すことができる（これには、引数、変数の代入、戻り値などが含まれる）
• Xdebugは、標準的なPHPのエラー報告にも改良を加える（後で詳しく説明します）

各種機能を駆使して、Xdebug（そして同様のデバッガ）をワークフローにあわせて使うことができます。次のセクションでは、その方法を説明します。

Xdebugを使う理由

サードパーティのツールや拡張機能を使った専用のデバッグワークフローを持つ開発者は、そこまで多くないかもしれません。と言うのも、PHPには基本的なエラーロギングが含まれているからです。変数や関数の呼び出しの結果を見るには、error_log、var_dump、printのようなコマンドを使うことができます。

例えば、WordPressの開発時に繰り返し使えるスニペットはネット上にたくさんあります。Stack Overflowがその良い例です。

function log_me($message) {
  if ( WP_DEBUG === true ) {
      if ( is_array($message) || is_object($message) ) {
          error_log( print_r($message, true) );
      } else {
           error_log( $message );
      }
  }
}

しかし、この方法にはいくつかの重要な欠点があります。

• まず、使用しているプラットフォームでエラーログを有効にしておく必要があります。この場合、WP_DEBUGを有効にします（これについては、後ほど詳しく説明します）。
• この「ダンプ」デバッグの例では、ステップ実行によるデバッグよりも調査範囲が狭くなります。はっきりと定義したものしか出力できません。

後者は、特に本職がシステム管理者でない場合、多くの作業が必要になります。例えば、あるコードブロックをデバッグしたい場合、自分で定義した変数に基づいてコードを追加することになります。しかし、狙いを定めたものが問題の原因ではない可能性があり、全くの見当違いということもあり得ます。

その代わりにXdebugのようなツールを使うことで、より大きな範囲を対象にできます。

• 実行中のさまざまな地点でコードを「分割」することで、リアルタイムで何が起こっているかを確認できる
• コードが何をしているか、どのように反応しているかを確認できるように、無数のメトリクス、視覚化、ブランチなどが用意されている
• 時には、デバッグ中にその場で値を変更することも可能（機能しているコードであっても、非常に大きな価値をもたらすもので、基本的にはいつでも手動で単体テストを実施可）
• ブレークポイントを使用してデバッグする領域をマークアップするため、コード内のスニペットで作業する必要がない（これにより、コードがクリーンに保たれ、その後に発生し得る問題の数を減らすことができる）

総じて、Xdebugのようなツールの使用は、受動的というよりむしろ積極的なものです。テスト駆動開発（TDD） の一環として単体テストを実装するのと同じように、 開発プロセスの中核としてステップデバッグを使用することができます。

PHPのエラーログを有効にする方法

特定のエラーがなくてもコードをデバッグすることはでき、 Xdebugを開かずに問題が発生したかどうかを知ることができれば、非常に便利です。これが、より詳しい調査を行うための出発点となります。厳密には必須のステップではありませんが、知っておいて損はないでしょう。

発生したすべてのエラーが報告されるようにするには、関連するPHPファイルの先頭に次の一行を追加する必要があります。

error_reporting(E_ALL);

これはキャッチオールコマンドであり、次のようにini_set関数を使用することもできます。

ini_set('error_reporting', E_ALL);

これにより、プロジェクトごとにphp.iniファイルの設定を変更することができます。このファイルで手動で変更することもできますが、ini_setを使って特定のパラメータを変更する方が一般的に好都合です。

ini_set('display_errors', '1');

エラーレポートを好みの設定にしたら、Xdebugを使って作業を始めることができます。

Xdebugの使い方

これから何回かに分けて、Xdebugの使い方と、セットアップに必要な手順を説明します。ツールの全てを説明することはできませんが、クイックスタートガイドとして、利用開始の手助けにはなるかもしれません。

まず、Xdebugをインストールします。その方法を説明します。

1. オペレーティングシステム（OS）にXdebugをインストールする

Xdebugは様々なセットアップに対応しており、それぞれで正確な手順が若干異なります。OSレベルでは、いくつかの違いがあります。

• Windowsの場合：既存のPHPファイルとインストールウィザードを使用し、システムに適したバージョンをダウンロードするという、やや複雑なセットアッププロセスになります。
• Linuxの場合：この方法は非常に簡単です。パッケージマネージャを使用して、XdebugやPHP Extension Community Library (PECL)をインストールすることができます。
• Macの場合：こちらもまたシンプルです。PECLをインストールしたら、ターミナルインスタンスからpecl install xdebugを実行します。また、XCodeのコマンドラインツールとPHPがシステムにインストールされている必要があります。

しかし、ほとんどの場合、システムレベルでのXdebugのインスタンスに固執する必要はありません。代わりに、自身の特定の開発環境に統合する方が理に適っています。

2. 開発環境にXdebugを統合する

XdebugをOSにインストールしたら、実際の環境に接続します。

非常に多くの対応システムやツールがあり、そのすべてを紹介することはできません。後ほど、DevKinstaとPhpStormの両方について説明をします。とは言え、他にも人気の環境はたくさんあります。以下で、いくつか優れた選択肢を見てみましょう。

Varying Vagrant Vagrants（VVV）

VVVはMake WordPressのサイトで名前が挙がっている環境の一つです。

VVVにはデフォルトでXdebugが含まれていますが、利用するには有効化する必要があります。ターミナルでSecure Shell（SSH）を使って有効にすることができます。

vagrant ssh -c "switch_php_debugmod xdebug"

しかし、パフォーマンスが少し落ちるので、サイトをプロビジョニングする際には、このオプションを元に戻す必要があります。

Laravel Valet

Laravel Valetは、あらゆる機能が揃ったウェブ開発環境と言えます。今回の肝であるXdebugを統合することも可能です。

これを行うには、デバッガ用の設定ファイルを作成する必要があります。コマンドラインでphp --iniを使うとパスが返されます。

次に、追加の.iniファイルのパスに新しいxdebug.iniファイルを作成します。この例では、/opt/homebrew/etc/php/7.4/conf.dにあります。

このファイルを開いたら、ロード済み設定ファイル（メインのphp.iniファイル）へのパスも通してください。両方を開いた状態で、以下を一番下に追加します。

• php.ini：zend_extension="xdebug.so"
• xdebug.ini：xdebug.mode=debug

変更を保存したら、ターミナルからvalet restartを実行し、サイトのファイルのひとつにphpinfo(); exit;を追加します。ブラウザのページ再読み込みで、これが動作するかどうか確認してください。

sudo brew services restart phpを使ってPHPを再起動し、php --info | grep xdebugを使っての、Xdebugシステムインストールが正しいことの確認が必要になる場合があります。以下のスクリーンショットにあるように、出力にXdebug特有の行があることがわかります。

ここから、Xdebugを好みのコーディングエディタに組み込むことができます。

XAMPP

XAMPPもValetと同じように、いくつかのパートに分かれています。Windows版とmacOS版では、プロセスが2種類あります。

まずXAMPPをインストールし、php_xdebug.dllファイル（Windows）またはxdebug.soファイル（macOS）がシステム上に存在するかどうか、簡単にチェックします。

ファイルが存在すれば、設定に移ることができます。そうでない場合は、まずWindows用の正しいバイナリ（希望のPHPバージョン用の64ビットファイル）をダウンロードするか、Macを使用している場合はさらにいくつかの依存関係をインストールする必要があります。

Windowsの場合は、DLLファイルphp_xdebug.dllの名前を変更し、xamppphpextのファイルパスに移動します。次に、xamppphpphp.iniファイルを好みのコードエディタで開き以下を追加します。

output_buffering = Off

[XDebug]セクションに、次の3行を追加します。

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger

変更を保存したら、Apacheを再起動し、Xdebugのテストをしてください。

Macの場合は、ターミナルインスタンスでxcode-select --installを使ってXcodeのコマンドラインツールをインストールすることをお勧めします。その後、Homebrewを使ってインストールしたいパッケージが3つあります。

brew install autoconf automake libtool

場合によっては、コアプログラムとDeveloper Filesの両方を入手するために、XAMPPを再インストールする必要があります。これらのファイルのみを再インストールすることも可能ですが、まずは既存のセットアップのバックアップを取ることをお勧めします。

次に、お使いのシステムでXdebugのソースフォルダのダウンロードに移動し、TGZファイルを解凍します。ターミナルウィンドウでそのディレクトリに移動し、以下を実行します。

phpize
pecl install xdebug

ここでも、sudoを使用する必要があるかもしれないことに注意してください。ここから、XAMPPのphp.iniファイルを編集できます。ほとんどのmacOSでは、/Applications/XAMPP/xamppfiles/etc/php.iniにファイルがあります。このディレクトリにはxdebug.soファイルのパスもあります。これをメモしておき、このスニペットのファイルパスのプレースホルダーの代わりにしてください。

[xdebug]
zend_extension=/path/to/xdebug.so
xdebug.mode=develop,degug
xdebug.start_with_request=yes

これがうまくいくかどうかテストするには、メインのhtdocs XAMPPディレクトリに新しいxdebug_info.phpファイルを作成します。その中に、以下を追加してください。

<?php
xdebug_info();

そして、Apacheを再読み込みして、ブラウザでXdebugをテストしてください。

XdebugでPhpStormを使用する

OSと開発環境を通してXdebugをインストールしたら、デバッガそのものを表示する必要があります。これは、お好みのコードエディタや統合開発環境（IDE）から行うことになります。環境と同様に、多くの選択肢から選ぶことができ、それぞれアプローチが異なります。

とはいえ、多くの場合、JetBrainsのPhpStormが使用されています。実際、PhpStormは「WordPressを意識したアシスト」を提供しています。他にも多くの理由で、人気のある選択肢です。

JetBrainsのサイトにはXdebugとPhpStormの接続方法が詳しく書かれていますが、ここでもおさらいしておきましょう。

まず、「Preferences」ペーン内の「Languages & Frameworks」＞「PHP」ページに移動します。ここで「CLI Interpreter」のドロップダウンフィールドの隣にある「More Items」メニューを開きます。

これにより、PHPのバージョンとインタプリタに関するさらなる詳細が表示されます。「Configuration file」オプションの隣にある「More items」をクリックすると、php.iniファイルのフルパスが表示されます。

PHPのバージョンやインタプリタの詳細が表示されます。

次に、このPHPファイルを操作して、セットアップのプロセスを継続します。

php.iniファイルでの作業

まずは、XdebugがPhpStormでどのように動作するかに影響を与える行を編集することから始めます。

php.iniファイルの中で、以下の行を探し、削除するかコメントアウトしてください。

zend_extension=<path_to_zend_debugger>
zend_extension=<path_to_zend_optimizer>

これらの行はす必ず存在するわけではないので、表示されなくても気にしないでください。

そして、次の行をファイルに追加してください。

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"

このコードには、いくつか注意すべき点があります。

• すでに[xdebug]セクションがあるかもしれませんが、その場合は最初の指定を省略することができます。
• zend_extensionの項目は、接続するためにxdebug.soのフルパスを追加する必要がある可能性があります。
• プレースホルダーのように見えるかもしれませんが、xdebug.client_portパラメータを使ってコード内で設定を行います。

これらを追加したら、ファイルを保存して閉じ、コマンドラインからPHPバージョンをテストします（php --versionを使用）。

Xdebugが動作するバージョンであれば、PHPの拡張機能の一つとして表示されます。また、新規ファイルにphpinfo();を追加して、ブラウザでテストすることも可能です。

これで、XdebugをPhpStormのデフォルトデバッガとして動作させることができます。最後に、ブラウザヘルパ拡張機能をインストールします。

ブラウザヘルパ拡張機能のインストール

最後にブラウザとPhpStormの間の接続を行います。サーバー上でステップデバッグを有効にすることでこれを実現します。特別な値GETやPOSTを使ってコマンドラインからこれを行うこともできますが、拡張機能を使うほうがより簡単です。

専用のXdebug Helperエクステンションを利用することをお勧めします。お好みのブラウザにインストールすることができます。

• Chrome/Chromium/Brave用Xdebugヘルパ
• Firefox用Xdebugヘルパ

他の拡張機能をお探しの場合は、JetBrains社のウェブサイトで確認してみてください。

選択したブラウザの拡張機能をインストールしたら、それ以上の構成を調整する必要はありません。ここから、PhpStormでXdebugを使い始めることができます。

Xdebugの使用

ここではPhpStormを使用しますが、別のIDEであってもレイアウトやインターフェースは似通ったものになっています。

デバッグの全体像を形成するために、各部位を理解しておきましょう。

• Breakpoints/ブレークポイント：Xdebugが出力を確認するために停止するポイントを指定できます。好きなだけ設定可能です。
• Listening for connections/接続のリッスン：この機能はオンとオフの切り替えができますが、通常、常にオンのままにしておくのが堅実です。
• The debugging screen/デバッグ画面：この画面でさまざまなコード、変数、パラメータを操作することができます。

最初のステップとして、リスニングを有効にします。これなしでは何もデバッグできません。ツールバーの「Run」＞「Start Listening for PHP Debug Connections」オプションをクリックします。

別の方法として、PhpStormのツールバー内の“電話”のアイコンをクリックすることも可能です。

これらオプションのいずれかが、接続のリッスンを開始します。

ここから、コードエディターのガター内にブレークポイントを設定することができます。赤い点はブレークポイントを示しており、これをクリックすることで有効にできます。

 

コードをデバッグする最も簡単な方法は、リスニングを始め、ブレークポイントを設定し、ブラウザで特定のページに移動することです。ブラウザ内で拡張機能のアイコンを見つけ、それをクリックし、「Debug」を選択します。

これにより、PhpStormのデバッガが開き、状態が確認できます。

様々な値、属性、パラメータ、変数を右クリックすると、さらにコンテキストメニューにアクセスすることができます。これにより、コードのテストやデバッグを行う自由度が広がります。

例えば、パスに沿った変数に異なる値を設定できます。コードをわざと壊して何が起こるか試すこともできますし、すでに修正が必要なコードへの対処としても使えます。いずれにせよ、コードを変更することなくデバッグするのに有用です。

KinstaとWordPressサイトのデバッグ（活用方法）

WordPressには、WP_DEBUGやQuery Monitorなど、独自のデバッグオプションがあります。これを使うことで、サイトとダッシュボードの至る所で、（以前は隠れていた）エラーメッセージを見ることができます。そして、そこから、何が問題なのかを解明することが可能です。

また、WP_DEBUG_LOGを使ってエラーメッセージを保存すれば、サイトの問題を文書化することができます。この設定方法については、こちらの記事で説明しています。MyKinsta（「サイト」＞「ツール」画面）から簡単に設定することができます。

これを無料のローカル開発ツールDevKinstaと組み合わせ、構築する各サイトのWP_DEBUGをワンクリックで有効・無効にすることもできます。

 

これにより、開発中にサイトのエラーをキャッチし、本番サイトにその影響が出ないようにすることができます。これらのモードはまた、サイトとユーザー両方のセキュリティにとって重要であり、簡単にオフに切り替え可能です。

すべてのKinstaプランには、WordPressサイトを考え設計されたパフォーマンス監視ツールであるKinsta APMも組み込まれています。

コマンドのチートシート

この記事をまとめる前に、ショートカットについて触れておきます。

他の多くのソフトウェアと同様に、Xdebug (および PhpStorm) でもキーボードだけで操作する方法がいろいろとあります。実際、PHPスクリプトのデバッグにコマンドラインを使用することも可能です。

Xdebugを起動したら、以下のコマンドを使用して移動することができます。

特定のコードエディタには専用のショートカットがありますが、ここではPhpStormに焦点を当てます。PhpStormでXdebugを使用するキーボードショートカットは以下の通りです。

覚えることは、そこまで多くありません。デバッガを開き、行ごとにブレークポイントを設定し、接続を待ち、スクリプトを実行するのが基本です。

そして、特定のタスクのショートカットが必要な場合は、PhpStormのFind Actionコマンドを使用することができます。

このスペースに入力を始めると、コマンドと関連するショートカットのリストが表示されます。また、「Help」＞「Keyboard Shortcuts PDF」メニューから、すべてのキーボードショートカットのPDF版を見つけることができます。

マウスで作業しながらショートカットをリアルタイムで確認するには、JetBrains提供のKey Promoter Xプラグインを使用することができます。

 

これを使用すると、最近実行したアクションの通知と、関連するキーボードショートカットが表示されます。一度、ショートカットを覚えてしまえば、あとはこのプラグインを段階的に削除して、スペースを解放するのがいいでしょう。

まとめ

デバッグの実践は、シンプルなところから始まり、長い道のりを経て、今では（その祖先が想像し得なかったくらいに）ずっと広い範囲をカバーしています。PHPコードの修正を徹底的に行うには、優れたツールを使用する必要があります。有用な拡張モジュールやツールは数多くありますが、Xdebugはその筆頭と言えるでしょう。

これまで見てきたように、Xdebugはあらゆるコードエディタに適応でき、PhpStormと組み合わせると特に素晴らしいものになります。セットアップに関係なく、あらゆる人のニーズを満たすはずです。全体として、強力で、柔軟性があり、直感的に使えるツールです。

Xdebugは高い評価に値すると思いますか？それとも、他のデバッグツールの方がお好みですか？以下のコメント欄でお聞かせください。