SSH トンネル経由のリモートデバッグ
このチュートリアルでは、SSH トンネル (SSH ポート転送とも呼ばれます) を使用して、Xdebug を実行しているリモートサーバーと PhpStorm を実行している開発マシンとの間に安全な接続を設定する方法について説明します。これは、間にファイアウォールがある場合、NAT ルーターが直接接続を妨げている場合、または ISP またはネットワークインフラストラクチャが開発者マシンへの受信 TCP 接続を許可していない場合に、リモートマシンでコードをデバッグできます。
リモートサーバーが開発者マシンに直接接続できる場合 (たとえば、Vagrant マシンを使用)、SSH トンネルは必要ない場合もあります。
前提条件
1. デバッガーはリモートサーバー上にセットアップされています
デバッグを開始する前に、PHP アプリケーションが実行される Web サーバーにデバッグエンジンがインストールされ、適切に構成されていることを確認してください。
PhpStorm は、最も人気のある 2 つのツール、Xdebug(英語) と Zend デバッガー(英語)によるデバッグをサポートしています。これらのツールは、互いにブロックし合うため、同時に使用することはできません。この問題を回避するには、Xdebug を構成するおよび Zend デバッガーの構成に従って、関連する PHP インタープリターの php.ini ファイルを更新する必要があります。
例: Xdebug では、サーバーの php.ini で次の設定が指定されていることを確認します。
zend_extension: Xdebug デバッグエンジンを使用することを示す設定。xdebugに設定するか、/usr/lib/php/20190902/xdebug.soなどのxdebug.soファイルへのフルパスを使用します。xdebug.mode: 有効にする Xdebug 機能を制御する設定。デバッグの場合はdebugに設定します。xdebug.client_host: PhpStorm が実行され、Xdebug からの受信接続を待機している IP アドレスまたはホスト名。xdebug.client_port: PhpStorm が実行されるホスト上で Xdebug が接続を試みるポート。デフォルトのポートは9003です。
2. PhpStorm では受信デバッガー接続のリッスンが有効になっています
PhpStorm では、次のいずれかを実行して、受信デバッグ接続のリッスンを有効にします。
ツールバー / ステータスバーの
をクリックします。メインメニューでを選択します。
これにより、Web サーバーでデバッグセッションが開始されると PhpStorm が反応し、デバッグツールウィンドウが自動的に開きます。デバッグセッションを開始する前に、ブレークポイントが設定されているか、設定ダイアログ Ctrl+Alt+S のデバッグページで PHP スクリプトの最初の行で中断するオプションが有効になっていることを確認してください。
SSH トンネルをセットアップする
デバッグセッションを開始すると、Xdebug がリモートサーバーから、PhpStorm がリッスンしている開発者マシンのポートへの TCP 接続を開始します。
SSH ポート転送の考え方は、リモートサーバー上に「仮想」TCP ポートを作成し、そのトラフィックを開発者マシン上の TCP ポートに送信して、トラフィックを SSH 経由でトンネリングすることです。
SSH トンネルをセットアップする
SSH ポート転送を設定するには、コマンドラインで次の ssh コマンドを実行します。
9003:localhost:9003の9003:は、 Xdebug 接続がlocalhostに転送される SSH サーバー (転送ホスト) 上のポートです。9003:localhost:9003のlocalhost:9003は、SSH クライアント (PhpStorm を実行しているマシン) の IP アドレスと、Xdebug 接続が転送されるポートです。localhostは、基本的に このsshコマンドを実行しているマシンです。username@hostnameは、SSH サーバー (転送ホスト) のアドレスと、そのサーバーでの SSH 認証に必要なユーザー名です。
SSH トンネルが正常に設定されていることを確認するには、PhpStorm ブックマークレット、ブラウザーデバッグ拡張機能、または PhpStorm を使用した PHP CLI スクリプトのデバッグで概説されている手法を使用して、リモートサーバーでデバッグセッションを開始します。PhpStorm が受信接続を検出するとすぐに、それを受け入れるように求める Xdebug からの受信接続ダイアログが表示されます。
PhpStorm でのデバッグプロセスの詳細については、ゼロコンフィギュレーションデバッグおよび中断されたプログラムを調べるを参照してください。
リモート PHP インタープリターまたは SSH トンネルを介して PHP CLI スクリプトをデバッグする
リモート PHP インタープリターが適切に設定されている場合、デバッグにリモート PHP インタープリターを利用して実行 / デバッグ構成を作成することが可能です。
SSH トンネルが稼働したら、PHP CLI スクリプトもデバッグできます。デバッガーはリモートマシン上で実行されるため、CLI デバッグセッションを開始するには、PHP コマンドラインスイッチを使用するか、（リモートマシン上の）環境変数を使用します。このワークフローは公式に推奨されているデバッグ方法ではありませんが、リモートサーバー側からデバッグセッションを確立する必要がある場合には便利です。
トラブルシューティング
デバッガーが接続しない、または接続を拒否する
デバッガーが接続できないか、接続を拒否する場合は、次の点を確認してください。
Xdebug が 127.0.0.1 およびポート 9000（Xdebug 2 の場合）またはポート 9003（Xdebug 3 の場合）に接続するように構成されていることを確認します。
Zend デバッガーを使用する場合は、PhpStorm ブックマークレットまたは Browser DebuggingExtension が 127.0.0.1 に接続するように構成されていることを確認してください。
SSH トンネルを設定する前に、PhpStorm が受信デバッガー接続をリッスンしていることを確認してください。
マシンが再起動されるか接続が失われると、SSH トンネルを再確立する必要があります。
リモートファイルパスがプロジェクト内のファイルパスにマップされていません
場合によってはデバッガーに接続できますが、リモートとプロジェクトファイル間のマッピングが定義されていないことを示すエラーメッセージが表示されます。これは、PhpStorm がデバッグ中のファイルに対応するローカルファイルを判別できないことを意味します。
この問題は、クリックしてパスマッピングを設定しますをクリックして、必要なパスマッピングを提供することで解決できます。さらに、Web サーバーに接続するで概説されている手法を使用して、これらのマッピングを構成できます。
関連ページ：
Vagrant: 再現可能な開発環境の使用
Vagrant は、仮想マシンのライフサイクルを管理するために使用されるコマンドラインユーティリティです。PhpStorm は、Vagrant との完全な統合を提供し、Vagrant 仮想環境の構成、仮想マシンの動作の制御、プロジェクト内からの Vagrant コマンドの実行を可能にします。Vagrant を使用する場合、次の定義が満たされます。Vagrantfile: Vagrant 環境を定義し、仮想ボックスのすべての構成を格納し、仮想マシンの操作方法を Vagrant に指示するメイン構成フ...
Xdebug を構成する
Xdebug をダウンロード PHP バージョンと互換性のある Xdebug 拡張をダウンロードし、Xdebug インストールガイドの説明に従ってインストールします。事前構成された AMP (Apache、MySQL、PHP) パッケージを使用している場合は、Xdebug 拡張機能がすでにインストールされている可能性があります。パッケージに固有の手順を参照してください。Xdebug と PHP エンジンの統合アクティブな php.ini ファイルをエディターで開きます。デバッグエンジンが PhpStor...
デバッグツールウィンドウ
デバッガーセッションを開始すると、デバッグツールウィンドウが表示されます。このウィンドウを使用して、デバッガーセッションを制御し、プログラムデータ（フレーム、変数など）を表示および分析し、さまざまなデバッガーアクションを実行します。これは、デバッグツールウィンドウの概要です。ツールウィンドウの使用に関する一般的な手順については、ツールウィンドウを参照してください。ツールウィンドウのタブを切り替えるには、とを押します。セッション：使用可能なデバッグセッションは、デバッグツールウィンドウの上部
ブレークポイント
ブレークポイントは、特定のポイントでプログラムの実行を一時停止する特別なマーカーです。これにより、プログラムの状態と動作を調べることができます。ブレークポイントは、たとえば、特定のコード行に到達したときにプログラムを一時停止するなどの単純なものから、追加の条件をチェックしたり、ログに書き込んだりするなどのより複雑なロジックを含むものまであります。ブレークポイントは、一度設定すると、一時的なブレークポイントを除き、明示的に削除するまでプロジェクト内に残ります。ブレークポイントの種類：PhpSto
デバッグ
このページは、PHP プラグインが有効な場合にのみ使用できます。PHP プラグインは PhpStorm にバンドルされており、デフォルトで有効になります。プラグインが無効になっている場合は、プラグインのマッピングの説明に従ってで有効にします。このページを使用して、Xdebug と Zend デバッガーの動作を設定します。事前構成この領域には、デバッガーのインストール、デバッガーのクッキーを制御してデバッグセッションを開始 / 停止するを実行するブックマークレットの生成、およびゼロコンフィギュレーショ...
ブラウザーのデバッグ拡張機能
デバッグを開始するには、まずサーバー上でデバッガーエンジンをアクティブにする必要があります。これを行うには、特別なまたはパラメーターを設定する必要があります (詳細については、Xdebug および Zend デバッガーの公式ドキュメントを参照してください)。手動で行うこともできますが、ワンクリックでデバッガーを有効にできるブラウザー拡張機能を使用する方が便利です。次の表に、使用可能なデバッグ拡張機能を示します。Xdebug ヘルパー Xdebug ヘルパーまたは Xdebug-extPhpStorm ブ...