インストール - Xdebug

提供：MochiuWiki : SUSE, EC, PCB
ナビゲーションに移動 検索に移動

概要

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プロジェクトがデバッグできるかどうか確認する。


「http://mochiuwiki.e2.valueserver.jp/index.php?title=インストール_-_Xdebug&oldid=11806」から取得