【WSL2】LANDOで構築したアプリをXDEBUGとPHPSTORMでデバッグする

sinceretechnology 2023/12/26(火) - 08:22

はじめに

WSLとは、Windows上でLinuxを動作させるための実行環境です。新しいバージョンである「WSL2」ではWindows上で「完全なLinux」が動かせるようになりました。またWINDOWS11ではWSL2でLINUX環境の構築がより簡単になったので、ローカル環境でLINUXのウェブサーバー環境の再現や動作テストも楽になりました。

今回はローカル環境にLANDOでWORDPRESSを構築して、プラグインやテーマなどの開発ができるように、PHPSTORMを使ってデバッグするまでの手順を記事にしました。

ローカル環境にLANDOでWORDPRESSを構築する手順は別の記事で説明していますのでそちらを御覧ください。

XDEBUG設定

XDEBUGが使えるようにするには、xdebugパッケージをサーバーにインストールして、php.iniに適切な設定をする必要があります。LANDOでは、.lando.ymlファイルにxdebug有効の設定をするだけでxdebugのインストールが可能です。

XDEBUGはXDEBUG2とDEBUG3では設定パラメータの名前が異なるので注意が必要です。

[PHP]

; Xdebug
xdebug.max_nesting_level = 256
xdebug.show_exception_trace = 0
xdebug.collect_params = 0
xdebug.mode = debug
xdebug.client_port = 9001
xdebug.start_with_request = yes
xdebug.client_host =  ${LANDO_HOST_IP}
xdebug.idekey = "PHPSTORM"

xdebug.client_host

xdebug.client_host = ${LANDO_HOST_IP}

client_hostには、変数LANDO_HOST_IPが設定されていますが、本来ここにはLANDOのホストPC（WSL2のLINUX）のIPアドレスを設定する必要があります。この設定が間違っていると、XDEBUGはデバッグ情報を外部に送信できないため、PHPSTORMでデバッグ行にブレイクポイントを設定してもいつまでたってもデバッグできないことになります。

実際には、LANDO_HOST_IPに次のホスト名が設定されています。

host.wsl.internal

そして、LANDOの設定ファイル（.lando.yml）の中で、このホスト名とLANDOのホストPCのIPアドレスが紐付けられています。

ホストPC（WSL2のLINUX)の設定

ホームディレクトリの.bashrc編集

ホストPC（WSL２のLINUX）ではホームディレクトリの.bashrcファイルに以下のコードを追加します。

// ~/.bashrc
# Set correct dev host to Windows
export LANDO_HOST_NAME_DEV=host.wsl.internal
export LANDO_HOST_GATEWAY_DEV=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}')
#optional: sudo sed -i "/$LANDO_HOST_NAME_DEV/d" /etc/hosts && sudo sh -c "echo $LANDO_HOST_GATEWAY_DEV $LANDO_HOST_NAME_DEV >> /etc/hosts"

名前host.wsl.internalは Lando 内で参照されるホスト名です。LANDO設定ファイル内でこのホスト名とここで変数に定義された実際のIPアドレス（LANDO_HOST_GATEWAY_DEV）が紐付けられます。docker の外部でも使用する場合は、bash を再起動するたびに、必要に応じnameserverて WSL ホストの現在の IP を更新できます。

ホームディレクトリの.lando/config.yml編集

// ~/.lando/config.yml
appEnv:
  LANDO_HOST_IP: $LANDO_HOST_NAME_DEV

LANDO設定ファイル編集

ホストPC側で設定した変数を使用して、XDEBUGに設定したホスト名host.wsl.internalにホストPCのIPアドレスを紐づけます。

// .lando.yml
services:
    appserver:
        overrides:
            extra_hosts:
                - ${LANDO_HOST_NAME_DEV:-host}:${LANDO_HOST_GATEWAY_DEV:-host-gateway}

全体の設定ファイルはこちらです。

name: wpxdbg-app
recipe: wordpress
config:
  webroot: webroot
  xdebug: true
  config:
    php: .lando_conf/php.ini
services:
  appserver:
    overrides:
      extra_hosts:
        - ${LANDO_HOST_NAME_DEV:-host}:${LANDO_HOST_GATEWAY_DEV:-host-gateway}
  phpmyadmin:
    type: phpmyadmin
    hosts:
      - database
~

PHPSTORMの設定

PHPSTORMを起動します。起動直後に表示される画面からNEWPROJECT FROM EXISTING FILEを選択してください。

ソースファイルはすでにLANDO環境内に存在するので一番上の項目を選択します。

次にデバッグ対象のソースフォルダ（ドキュメントルート）を選択します。

次にローカルサーバーを追加します

次にサーバーのURLを設定します。

LANDOで生成されたURLを設定します

SSLの場合は次の画面でACCEPTをクリックして下さい

ウェブルートパスを指定します。

XDEBUGに設定したポートを追加します

サーバー情報を設定します

このとき、ホストPCのフォルダとDOCKER内の対象のフォルダを指定してマッピングします。

次にデバッグ情報を設定します

次に、先ほど設定したサーバーとXDEBUGで指定したIDE KEYをここで設定します。

デバッグ行を設定します。ここではテストのため、wordpressのindex.phpの最初の行を設定しました。つぎに画面右上の電話のアイコンをクリックしてデバッグを有効にします。

ブラウザからサイトURLをアクセスすると、上で指定したデバッグ行で停止することが確認できます。

バックアップデータをLANDO環境に復元するときの注意点
１．サイトURLは自動で設定されるため、すでに公開しているサーバーのデータベースを復元する際は、データベース内のURLをLANDOで生成されたURLに変換する必要があります
２．デフォルトでドキュメントルートに.htaccessファイルが存在しません。パーマネントリンク設定をデフォルト以外にしている場合は、復元時にはこちらのファイルも必要です。

おわりに

いままでVIRTUALBOXやVMをインストールしてLINUXサーバーのデバッグやテストをしていましたが、WSL2では格段に速くなりました。LANDOではDOCKERとホストPCのドキュメントルートのコードが共有されています。デバッグ時に修正分を毎回ターゲットサーバーに反映する必要もなく、リアルタイムに更新されているのでデバッグが捗ります。これでWINDOWSとUBUNTUのデュアルブートから解放されます！