インストール - Xdebug

概要

Xdebugは、PHPの拡張機能の1つであり、PHPの開発環境を向上させる様々な機能を提供する。

• ステップデバッグ

  スクリプトの実行中に、IDEやエディタでコードをステップ実行する方法である。

  
  

• PHPのエラー報告の改善

  改良されたvar_dump関数、Notice、Warnings、Errors、Exceptionのスタックトレースにより、エラーが発生するまでのコードパスを強調して表示する。

  
  

• トレース

  全ての関数の呼び出しを、引数や呼び出し位置とともにディスクに書き込む。

  オプションで、各関数のすべての変数割り当てと戻り値も含まれる。

  
  

• プロファイリング

  視覚化ツールを使用して、PHPソフトウェアのパフォーマンスを分析して、ボトルネックを見つけることができる。

  
  

• コードカバレッジ分析

  PHP Unitでユニットテストを実行した際に、コードベースのどの部分が実行されたかを示す。

Xdebugのインストール

パッケージ管理システムからインストール

以下のコマンドを実行する。

# RHEL
sudo dnf install php84-php-pecl-xdebug3.x86_64  # PHP 8.4の場合
                 php83-php-pecl-xdebug3.x86_64  # PHP 8.3の場合
                 php82-php-pecl-xdebug3.x86_64  # PHP 8.2の場合
                 php81-php-pecl-xdebug3.x86_64  # PHP 8.1の場合
                 php81-php-pecl-xdebug3.x86_64  # PHP 8.0の場合
                 php74-pecl-xdebug3.x86_64      # PHP 7.4の場合

# SUSE
sudo zypper install php8-xdebug  # PHP 8の場合
                    php7-xdebug  # PHP 7の場合

ソースコードからインストール

Xdebugのダウンロード

まず、ApacheまたはNgineXを起動する。
ApacheまたはNgineXのルートディレクトリに、以下の内容のindex.phpファイルを作成する。

sudo vi /var/www/html/index.php
または
sudo vi /srv/www/htdoc/index.php

 <?php
    phpinfo();
 ?>

Webブラウザを起動して、http://localhost/ にアクセスする。
その時、インストール済みのPHPの環境が表示されるので、[Ctrl] + [A]キーを同時押下して、全てコピーする。

次に、必要なXdebugのバージョンを調べるため、以下のWebサイトにアクセスする。

https://xdebug.org/wizard.php

Webサイトのテキストボックスに、上記でコピーした情報を貼り付けて、[Analyse my phpinfo() output]ボタンを押下する。
Xdebugのダウンロードページが表示されるので、[Instruction]項目からXdebugをダウンロードする。

Xdebugのインストール

まず、Xdebugの公式Webサイトにアクセスして、Xdebugのソースコードをダウンロードする。
ダウンロードしたファイルを解凍する。

tar xf xdebug-<バージョン名>.tgz
cd xdebug-<バージョン名>

phpizeコマンドを実行する。

phpize

Xdebugをビルドおよびインストールする。
もし、configureスクリプトの実行に失敗する場合、Xdebugのビルドに必要なライブラリ等が不足している。

mkdir xdebug-build && cd xdebug-build

../configure \
             --enable-xdebug     \
             --enable-xdebug-dev \  # 任意
             --prefix=<PHPのインストールディレクトリ>  # PHPを任意のディレクトリにインストールしている場合等に指定する

make -j $(nproc)

make install
または
sudo make install

インストールしたxdebug.soファイルの場所は、各LinuxディストリビューションやPHPの環境により異なる。

RHELおよびSUSEにおいて、パッケージ管理システムからPHPをインストールした場合は、/usr/lib64/php<PHPのバージョン>/extensionsディレクトリに配置される。
ソースコードからPHPをインストールした場合は、/<PHPのインストールディレクトリ>/lib64/extensions/xxxディレクトリ等に配置される。

Xdebugの設定

Xdebugの設定ファイルを作成または開いて、以下の内容を追記する。
もし、OPCacheを使用する場合は、OPCacheの設定行の後にzend_extensionを入力すること。

Xdebugのバージョンにより、[xdebug]セクションの設定が異なることに注意すること。

# RHEL
sudo vi /etc/php.d/15-xdebug.ini                        # PHPをパッケージ管理システムからインストールしている場合
sudo vi /<PHPのインストールディレクトリ>/etc/conf.d/xdebug.ini  # PHPをソースコードからインストールしている場合

# SUSE
sudo vi /etc/phpX/conf.d/xdebug.ini                     # PHPをパッケージ管理システムからインストールしている場合  XはPHPのバージョン
sudo vi /<PHPのインストールディレクトリ>/etc/conf.d/xdebug.ini  # PHPをソースコードからインストールしている場合

• Xdebug 3.xの設定

  Xdebug 3.xの標準ポート番号は、9003番に変更されたことに注意すること。

  xdebug.remote_hostは、xdebug.client_hostに置き換えられた。

  xdebug.remote_portは、xdebug.client_portに置き換えられた。

  xdebug.remote_logは、xdebug.logに置き換えられた。

  これは Step Debugging以外のログメッセージも含まれる。

  
  

  xdebug.remote_modeは、以下に示す設定に置き換えられた。

  xdebug.remote_mode=req(デフォルト値)の場合は、xdebug.mode=debugとxdebug.start_with_request=triggerを使用する。

  xdebug.remote_autostartの動作が必要な場合は、xdebug.start_with_request=triggerの代わりにxdebug.start_with_request=yesを使用する。

  xdebug.start_with_request=jitの場合は、xdebug.mode=debugおよびxdebug.start_upon_error=yesを使用する。

# 1行目を編集
zend_extension = <配置したxdebug.soファイルのフルパス>

# ファイルの最後尾に以下の設定を記述
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.dump_undefined=1
xdebug.log="<出力したいログファイルのフルパス  例. /home/user/xdebug.log>"
xdebug.remote_handler=dbgp
xdebug.client_port=9003  ; 標準は9003番ポート
xdebug.client_host=127.0.0.1
xdebug.idekey=VSCODE

• Xdebug 2.xの設定

Xdebug 2.xの標準ポート番号は、9000番であることに注意すること。

# 1行目を編集
zend_extension = <配置したxdebug.soファイルのフルパス>

# ファイルの最後尾に以下の設定を記述
[xdebug]
xdebug.dump_undefined=1
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_log="/tmp/xdebug.log"
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_port=9000
xdebug.idekey=VSCODE

xdebug.iniファイルの設定を反映させるため、Apache2またはNginXを再起動する。

sudo systemctl restart apache2
または
sudo systemctl restart nginx

VSCodeの設定

VSCodeにてXdebugを使用する場合において、VSCodeの設定を記載する。
なお、VSCodiumにはバグが存在するため、Xdebugが使用できないので注意すること。

まず、以下に示すVSCodeの拡張をインストールする。

• PHP Extension Pack

  PHP IntelliSense

  PHP Debug

PHPプロジェクトのワークスペースにlaunch.jsonを追加して、以下のように設定を記述する。
VSCodeのメイン画面左にある[デバッガ]アイコンから歯車アイコンを押下してPHPを選択すると、launch.jsonファイルが自動作成される。
"Launch currently open script"では、Webブラウザと連携したデバッグができないため、注意すること。

• Listen for XDebug

  この設定は、XDebugの指定されたポート(初期は9000番)でリッスンを開始する。

  XDebugを構成する場合、Webブラウザを使用してWebサーバに要求を行う、または、CLIスクリプトを起動するたびにXDebugが接続して、

  ブレークポイントや例外等で停止することができる。

• Launch currently open script

  この設定は、CLIデバッグの例である。

  現在開いているスクリプトをCLIとして起動した後、デバッグコンソールに全てのstdout / stderr出力を表示して、

  スクリプトが終了するとデバッグセッションを終了する。

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

以下に、プロジェクト構成ファイルであるlaunch.jsonファイルの設定項目の意味を示す。

• request

  launchに設定する。

• hostname

  XDebugをリッスンする時にバインドするアドレス(標準 : 使用可能な場合は全てのIPv6接続、それ以外は全てのIPv4接続)

• port

  XDebugをリッスンするポート(標準 : 9000番)

• stopOnEntry

  スクリプトの開始時に中断するかどうか(標準 : false)

• pathMappings

  PCのローカルソースパスにマッピングされているサーバパスのリスト

  詳細は、リモートホストのデバッグを参照すること。

• log

  VSCodeとアダプタ間の全ての通信をデバッグコンソールに記録するかどうか。

  さらに下のトラブルシューティングを参照してください。

• ignore

  エラーを無視する必要があるglobパターンのオプションの配列

  例 : **/vendor/**/*.php

• xdebugSettings

  XDebugのリモートデバッグの設定をオーバーライドして、XDebugをニーズに合わせて微調整できる。

  例えば、max_childrenとmax_depthを操作して、取得する配列、オブジェクトの子の最大数、配列やオブジェクト等の構造体の最大深度を変更できる。

  これにより、デバッガを高速化できる。

  設定できる機能名の完全なリストについては、XDebugのドキュメントを参照すること。

• max_children

  最初に取得する配列またはオブジェクトの子の最大数。

• max_data

  最初に取得する変数データの最大量。

• max_depth

  配列、ハッシュ、オブジェクト構造をIDEに送信する時、デバッガエンジンが返す可能性のある最大の深さ。

• show_hidden

  この機能は、プロパティ(クラスのプライベートメンバ等)に関する詳細な内部情報が必要な場合に、IDEによって設定できる。

  例えば、この値を0にすると、非表示のメンバがIDEに表示されないことを意味する。

CLIデバッグの固有のオプション

• prgram

  起動する必要のあるスクリプトへのパス。

• args

  スクリプトに渡される引数。

• cwd

  スクリプトの起動時に使用する現在の作業ディレクトリ。

• runtimeExecutable

  スクリプトの起動に使用されるPHPバイナリ(Windowsの場合、php.exe)へのパス。

• runtimeArgs

  PHPバイナリ(Windowsの場合、php.exe)に渡す追加の引数。

• externalConsole

  デバッグコンソールではなく、外部コンソールウィンドウでスクリプトを起動する。(標準 : false)

• env

  スクリプトに渡す環境変数。

Codiumの設定

CodiumにPHP Debug extensionがインストールされていないことを確認する。
もし、PHP Debug extensionがインストールされている場合は、アンインストールする。

以下に示すURLにアクセスして、ページ右にある[Resources] - [Download Extension]を選択して、vsixファイルをダウンロードする。
https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug

Codiumのメイン画面左にある[拡張機能]サイドバーから、[拡張機能]画面左上にある[...]ボタンを押下する。
[VSIXからのインストール...]を選択して、ダウンロードした拡張ファイルを選択する。

Xdebug 3.0以降を使用する場合は、php.iniファイルのxdebugセクションを、以下のように変更する必要がある。
ただし、CodiumのPHPプロジェクトにあるlaunch.jsonファイルにおいて、ポートを9003に変更することにより、xdebug.client_port=9000の設定は記述しなくともよい。

xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9000

確認方法

以下のコマンドを入力して、xdebugと表示されているならば成功である。

php -m | grep xdebug

Webブラウザと連携

PHPのデバッグにおいて、Webブラウザと連携すると開発効率が上がる。(例 : Get & Postのデバッグ等)

Webブラウザと連携する方法は、Webブラウザの拡張機能であるxDebug Helperをインストールする。

• FireFox
  1. Firefoxを起動して、[ツール]メニューバー - [アドオン]を選択する。
  2. 表示される画面上部にある[アドオンを探す]検索欄から、"Xdebug Helper"と入力する。
  3. Xdebug Helper for Firefoxをインストールする。
• ChromeおよびVivaldi
  1. https://chrome.google.com/webstore/category/extensions にアクセスする。
  2. 検索項目に"xDebug Helper"と入力して、xDebug Helperをインストールする。

リモートデバッグ

リモートサーバ側の設定

Xdebugの設定ファイルに、以下の設定を追記する。

sudo vi /etc/php7/conf.d/xdebug.ini

# /etc/php7/conf.d/xdebug.iniファイル

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.dump_undefined=1
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_log=<デバッグ用ログファイルのフルパス>  ; 例 : /tmp/xdebug.log
xdebug.remote_host=<開発PCのIPアドレス>               ; 例 : 192.168.1.0/24
xdebug.remote_port=<任意のポート番号>                 ; 例 : 9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.client_port=9000
; xdebug.client_host=127.0.0.1
xdebug.idekey=VSCODE

次に、SSHの設定ファイルに、以下の設定を追記する。
SSHが未インストールまたは未設定の場合、設定 - SSHのページを参照すること。

sudo vi /etc/ssh/sshd_config

# /etc/ssh/sshd_configファイル

GatewayPorts yes

設定後、SSHサービスを再起動する。

sudo systemctl restart sshd

開発用PCの設定

まず、リモートサーバにあるPHPプロジェクト(ドキュメントルートにあるファイル)を開発用PCにコピーする。

rsync -avz --rsync-path="sudo rsync" --delete --rsh="ssh" <リモートサーバのユーザ名>@<リモートサーバのIPアドレス>:<ドキュメントルートのフルパス> <開発用PCのPHPプロジェクトのフルパス>

次に、リモートサーバと開発環境の間にSSHトンネルを作成する。
ターミナルよりもVSCode等のIDE付属ターミナルで実行する方が便利である。

ssh -R <VSCode等のIDEで設定する任意のポート番号>:<開発用PCのIPアドレス>:<xdebug.remote_portで設定したポート番号> <リモートサーバのユーザ名>@<リモートサーバのIPアドレス>

# 例
ssh -R 9000:192.168.1.10:9000 hoge@192.168.1.20

VSCodeで開発を行う場合、VSCodeからPHP Debug拡張機能をインストールする。
launch.jsonファイルに、以下の設定を追記する。

 // ...略
 
 {
    "name": "Listen for XDebug",
    "type": "php",
    "request": "launch",
    "port": <上記のsshコマンドで設定した任意のポート番号>,
    "log": true,
    "pathMappings": {
       "<Webサーバのドキュメントルートのフルパス>": "${workspaceFolder}"
    }
 }
 
 // ...略

最後に、PHPプロジェクトがデバッグできるかどうか確認する。